rudder-csharp-sdk/skills/rudder-csharp-sdk/reference/errors.md

Errors, exceptions, error codes

Source: Exceptions/*.cs, Models/RudderErrorCodes.cs, Models/ErrorResponse.cs, HttpClientTransport.cs (status mapping).

Exception hierarchy

All API failures derive from RudderApiException:

public class RudderApiException : Exception
{
    public int StatusCode { get; }     // 0 when the request never reached the server
    public string Code { get; }        // machine-readable API error code, "" when absent
    public string? RequestId { get; }  // server-issued request id for support tickets
}

Exception	When
RudderAuthException	HTTP 401 after the automatic refresh+retry also failed — session is over, sign in again
RudderNotFoundException	HTTP 404
RudderRateLimitException	HTTP 429 — back off and retry later
RudderApiException (base)	any other non-success status
RudderNetworkException	DNS/connectivity failure or client-side timeout; StatusCode == 0; retrying is safe for idempotent operations

The transport parses the error body as ErrorResponse:

public class ErrorResponse   // RudderSdk.Core.Models
{
    public string? Code { get; set; }       // "code"
    public string? Error { get; set; }      // "error" — human-readable message
    public int? Index { get; set; }         // "index"
    public string? PlayerId { get; set; }   // "playerId"
    public string? RequestId { get; set; }  // "requestId"
}

Non-JSON error bodies fall back to the HTTP reason phrase.

Error code constants

RudderSdk.Core.Models.RudderErrorCodes (generated; scenario/battle-pass/quest domain codes):

EarlyCompletion       = "early_completion"
Forbidden             = "forbidden"
LevelNotReached       = "level_not_reached"
NodeNotActive         = "node_not_active"
ObjectivesIncomplete  = "objectives_incomplete"
RunExpired            = "run_expired"
RunNotActive          = "run_not_active"
ScenarioNotActive     = "scenario_not_active"
UnknownRun            = "unknown_run"

Match against RudderApiException.Code.

Scenario callback / counter errors

On POST /sdk/v1/scenarios/callback and POST /sdk/v1/scenarios/counter, unknown_run, run_expired, and HTTP 404 drop that run and fire Effects.OnScenarioFailed. Other callback errors propagate to the caller. A failed counter update that is not one of those definitive rejections is logged via IRudderLogger and the effect stays active. Details: reference/scenarios.md.