> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musterbox.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> SDK error codes, mapping tables, and handling guidance.

The SDK reports failures as structured errors with stable codes, so you can
map them to player-facing and operator-facing behaviour without string
matching.

## Native error model

`SdkError` variants carry an `SdkErrorCode`:

| Code                                      | Meaning                                        | Handling                                  |
| ----------------------------------------- | ---------------------------------------------- | ----------------------------------------- |
| `MBX-SDK-001` InvalidConfig               | Configuration failed validation                | Fix config; retry initialize              |
| `MBX-SDK-002` MismatchedVersion           | SDK/ABI/protocol/config version mismatch       | Upgrade the adapter to match core         |
| `MBX-SDK-003` RouteError                  | Unknown path or routing failure                | Report a bug (SDK misroute)               |
| `MBX-SDK-004` TransportError              | Network failure (connect/request timeout, DNS) | Retry with backoff; check environment URL |
| `MBX-SDK-005` AuthenticationFailed        | Login/refresh rejected                         | Re-authenticate or surface login error    |
| `MBX-SDK-006` MfaRequired                 | Backend signals `requiresOTP`                  | Inform player OTP unsupported yet         |
| `MBX-SDK-007` NotAuthenticated            | No valid session                               | Authenticate first                        |
| `MBX-SDK-008` SessionLost / RefreshFailed | Token refresh failed repeatedly                | Re-authenticate                           |
| `MBX-SDK-009` ProtocolError               | Message fails protocol validation              | Drop/resubmit event; check payload limits |
| `MBX-SDK-010` EnvironmentError            | Host integrity / diagnostics failure           | Surface integrity block                   |
| `MBX-SDK-011` EventQueueFull              | Outbound backpressure                          | Retry after drain                         |
| `MBX-SDK-012` StorageError                | Journal/storage failure                        | Run `musterbox storage verify`            |
| `MBX-SDK-013` InternalError               | Unhandled failure                              | Capture diagnostics; file ticket          |

<Note>Codes above map the public contract. See the crate-level `error::SdkErrorCode` documentation for the authoritative display strings.</Note>

## Browser error model

`@musterbox/sdk-js` mirrors codes as structured error objects:

```ts theme={"dark"}
try {
  await box.authenticate({ identifier, password });
} catch (err) {
  if (err.code === "MBX-SDK-005") {
    showLoginError("Invalid credentials");
  } else if (err.code === "MBX-SDK-013") {
    captureDiagnostics(box.getDiagnostics());
  }
}
```

## Engine adapters

Unity, Godot, Unreal, Cocos, and Defold translate errors into their idioms
(`Result<T>`/exceptions/boolean + error object) while preserving the code
behind message text. See the relevant [engine page](/engines/unity).

## Error handling rules of thumb

* **Never** treat transport errors as terminal — retry with the SDK's backoff
  (`max_retry_attempts` = 5).
* **Never** fall back to unauthenticated privileged calls after
  `NotAuthenticated`.
* **Never** retry `verify_pin` (single-shot) — see
  [Secure purchases](/sdk/purchases).
* **Always** capture diagnostics before filing an incident.

Next: [CLI](/sdk/cli).