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`:

```csharp
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`:

```csharp
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):

```csharp
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.