Errors

Direct HTTP integrations receive standard status codes plus SkyState error bodies where applicable. The JavaScript SDKs translate these into SkyStateError values, subsystem status snapshots, and React onError callbacks depending on where the error occurs.

Common situations that result in errors:

• Route target not found - the project or account route identifier is not recognized; an invalid environment value (not one of development, staging, production) returns 400 instead
• No state yet - public-state and user-state reads can return 204; SDK keyed reads continue to use their fallback value
• Quota exceeded - the account's monthly API-request quota or another tier limit has been reached; see Rate Limiting
• Authentication failure - the API key is invalid or has been revoked; see Dev API Keys
• Version conflict - a write used an outdated If-Match version and returned 412
• Quota failure - a write would exceed a tier limit, such as the Stored Users limit for user state

SDK error codes

The SDK translates HTTP responses to typed SkyStateError values with a code: SkyStateErrorCode field. The full code list, HTTP-status-to-code mapping, and drain-result behavior are covered in this page and in the SDK core reference. The canonical error-code mapping (Section 8.5) lives in the repository specification document (docs/3_specification.md).

Common codes you may narrow on:

• configuration - unknown account or project (404); stop, no retry
• authentication - token refresh failed or write attempted without sign-in
• conflict - If-Match version mismatch (412); SDK refetches and replays automatically
• quota - monthly request quota or tier limit exceeded (402)
• authz - caller authenticated but not permitted (403)
• network - non-classified HTTP error or network failure; SDK retries with backoff
• validation - invalid key format, non-JSON value, or server-rejected patch (400)

For SDK-specific error handling, see the SDK docs.