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

Codes above map the public contract. See the crate-level error::SdkErrorCode documentation for the authoritative display strings.

Browser error model

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

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.

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.
• Always capture diagnostics before filing an incident.

Next: CLI.