> ## Documentation Index > Fetch the complete documentation index at: https://docs.kynasmith.dev/llms.txt > Use this file to discover all available pages before exploring further. # Error codes > Complete reference of API error codes, HTTP statuses, and recommended actions. # Error codes All Kynasmith API errors follow a consistent envelope: ```json theme={null} { "error": { "code": "error_code_string", "message": "Human-readable description of what went wrong.", "retryable": false, "details": {} } } ``` * `code` — A machine-readable string identifying the error type. * `message` — A human-readable explanation. Do not parse this programmatically. * `retryable` — Whether the request can be retried without changes. * `details` — Additional structured context (varies by error code). ## General API errors | Code | HTTP Status | Retryable | Description | Recommended Action | | ---------------------- | ----------- | --------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `access_token_missing` | 401 | No | No `Authorization: Bearer` header provided. | Add a valid bearer token to the request. | | `access_token_invalid` | 401 | No | The access token is malformed or has been revoked. | Mint a new access token. | | `access_token_expired` | 401 | Yes | The access token has expired. | Refresh or re-mint the access token. | | `insufficient_scope` | 403 | No | The token does not have the required scope for this operation. | Mint a token with the required scopes. See [scopes reference](/get-started/authentication#access-token-scopes). | | `project_mismatch` | 403 | No | The `project_id` in the request does not match the token's project scope. | Use the correct project ID or mint a token for the target project. | | `authorization_failed` | 403 | No | General authorization failure. | Check that your credential has access to the requested resource. | | `not_found` | 404 | No | The requested resource does not exist. | Verify the resource ID. | | `validation_error` | 422 | No | The request body failed schema validation. | Check the `details` field for specific field errors. | | `conflict` | 409 | No | The operation conflicts with the current resource state. | Read the current resource state and retry with the correct preconditions. | | `rate_limited` | 429 | Yes | Too many requests. See [Rate limits](/api-reference/rate-limits). | Back off and retry after the `Retry-After` header duration. | | `internal_error` | 500 | Yes | An unexpected server error occurred. | Retry with exponential backoff. If persistent, contact support with the `X-Request-ID`. | | `service_unavailable` | 503 | Yes | The service is temporarily unavailable. | Retry with exponential backoff. | ## MoveSpec errors | Code | HTTP Status | Retryable | Description | Recommended Action | | ---------------------------- | ----------- | --------- | ----------------------------------------------------------- | ------------------------------------------------------------------- | | `movespec_not_found` | 404 | No | The MoveSpec resource does not exist. | Verify the `movespec_id`. | | `movespec_version_not_found` | 404 | No | The MoveSpec version does not exist. | Verify the `movespec_version_id`. | | `draft_validation_failed` | 422 | No | The draft YAML has blocking validation errors. | Fix the errors listed in the validation response, then re-validate. | | `version_already_released` | 409 | No | The version is already in the released state. | No action needed — the version is already active. | | `no_released_version` | 404 | No | The MoveSpec has no released version to resolve at runtime. | Release an immutable version before creating sessions. | ## Detection session errors | Code | HTTP Status | Retryable | Description | Recommended Action | | ------------------------------ | ----------- | --------- | ---------------------------------------------------------------- | -------------------------------------------------- | | `session_not_found` | 404 | No | The detection session does not exist. | Verify the `session_id`. | | `session_already_completed` | 409 | No | The session has already reached a terminal state. | Create a new session. | | `session_already_cancelled` | 409 | No | The session was cancelled. | Create a new session. | | `contract_version_unsupported` | 422 | No | Your SDK version is not compatible. | Update your SDK to the latest version. | | `duplicate_active_connection` | 409 | No | Another WebSocket connection is already active for this session. | Close the existing connection before reconnecting. | ## Billing and quota errors These errors are returned when operations are denied due to billing or plan limits. | Code | HTTP Status | Retryable | Description | Recommended Action | | ------------------------ | ----------- | --------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | `quota_exceeded` | 403 | No | Your organization has exceeded its plan's usage quota. | Upgrade your plan or wait for the quota reset. Check `details.quota_limit`, `details.current_usage`, and `details.resets_at`. | | `organization_suspended` | 403 | No | The organization has been suspended. | Contact support or resolve the suspension reason in the portal. | | `delinquent_payment` | 403 | No | The organization has an overdue payment. | Update your payment method in the portal at [app.kynasmith.dev](https://app.kynasmith.dev). | | `plan_requires_upgrade` | 403 | No | The requested feature is not available on your current plan. | Upgrade your plan in the portal. | | `billing_not_configured` | 403 | No | Billing has not been set up for this organization. | Configure billing in the portal under **Settings > Billing**. | ### Billing error response example ```json theme={null} { "error": { "code": "quota_exceeded", "message": "Organization has exceeded the monthly accepted-frames quota.", "retryable": false, "details": { "quota_limit": 10000, "current_usage": 10001, "resets_at": "2026-05-01T00:00:00Z", "upgrade_url": "https://app.kynasmith.dev/settings/billing" } } } ``` ## Distinguishing rate limits from billing errors * **Rate limiting** (`rate_limited` / HTTP 429): Abuse protection that applies equally to all customers. Retry after the indicated duration. * **Billing errors** (`quota_exceeded`, `plan_requires_upgrade` / HTTP 403): Plan-based limits tied to your organization. These require a plan change or waiting for quota reset, not just retrying. Both SDKs map these to distinct error types (`RateLimitError` vs. `AuthorizationError`) so you can handle them differently in your code.