Errors
Every error response includes ok: false and a code. Codes below are generated from contracts/error-codes.json with default HTTP status and retry safety.
Error envelope
json
{
"ok": false,
"code": "AUTH_REQUIRED",
"detail": "Authentication required.",
"error": "Authentication required."
}
{
"ok": false,
"code": "AUTH_REQUIRED",
"detail": "Authentication required.",
"error": "Authentication required."
}Reference
| Code | Status | Domain | Retry? | Default message |
|---|---|---|---|---|
BAD_REQUEST | 400 | common | No | The request is invalid. |
AUTH_INVALID_SESSION | 401 | auth | No | Invalid session. |
AUTH_REQUIRED | 401 | auth | No | Authentication required. |
AUTH_SESSION_EXPIRED | 401 | auth | No | Session expired. |
AUTH_USER_UNAVAILABLE | 401 | auth | No | User not available. |
BILLING_INSUFFICIENT_CREDITS | 402 | billing | No | Insufficient credits. |
AUTH_ADMIN_ACCESS_DENIED | 403 | auth | No | Admin console access denied. |
AUTH_ADMIN_ROLE_REQUIRED | 403 | auth | No | Admin role required. |
FORBIDDEN | 403 | common | No | Forbidden. |
RESOURCE_NOT_FOUND | 404 | common | No | Resource not found. |
CONFLICT | 409 | common | No | The request conflicts with current state. |
STUDIO_AUDIO_EXPORT_BLOCKED | 409 | studio | No | Studio audio export is blocked by missing or stale clips. |
STUDIO_AUDIO_EXPORT_INCOMPATIBLE_AUDIO | 422 | studio | No | Studio audio export requires compatible PCM WAV clip audio. |
STUDIO_AUDIO_EXPORT_NO_AUDIO | 422 | studio | No | Studio audio export has no clip audio to export. |
STUDIO_AUDIO_EXPORT_UNSUPPORTED_SOURCE | 422 | studio | No | Studio audio export requires supported clip audio sources. |
VALIDATION_ERROR | 422 | common | No | Request validation failed. |
GENERATION_NOT_READY | 425 | generation | Yes | Generation is not ready yet. |
GENERATION_CONCURRENCY_EXCEEDED | 429 | generation | Yes | Your plan's concurrent generation limit was reached. Please retry shortly. |
RATE_LIMITED | 429 | common | Yes | Rate limit exceeded. |
INTERNAL_ERROR | 500 | common | Yes | Internal server error. |
STUDIO_AUDIO_EXPORT_FAILED | 500 | studio | Yes | Studio audio export failed. |
GENERATION_FAILED | 502 | generation | Yes | Generation failed. |
GENERATION_INVALID_RESPONSE | 502 | generation | Yes | Generation service returned an invalid response. |
UPSTREAM_ANALYTICS_ERROR | 502 | upstream | Yes | Analytics service request failed. |
UPSTREAM_BILLING_ERROR | 502 | upstream | Yes | Billing service request failed. |
UPSTREAM_GENERATION_ERROR | 502 | upstream | Yes | Generation service request failed. |
UPSTREAM_GENERATION_SERVICE_ERROR | 502 | upstream | No | Generation service request failed. |
VOICE_CLONE_FAILED | 502 | voice | Yes | Voice clone failed. |
VOICE_DESIGN_FAILED | 502 | voice | Yes | Voice design failed. |
AUTH_CONFIG_MISSING | 503 | auth | No | Authentication is not configured correctly. |
GENERATION_CAPACITY_EXCEEDED | 503 | generation | No | Generation capacity is currently exhausted. Please try again shortly. |
LLM_CONFIG_NOT_FOUND | 503 | upstream | No | LLM feature is not configured. |
STUDIO_AUDIO_EXPORT_ASSET_READ_FAILED | 503 | studio | Yes | Studio audio export could not read clip audio from storage. |
STUDIO_AUDIO_EXPORT_ASSET_WRITE_FAILED | 503 | studio | Yes | Studio audio export could not write the result to storage. |
STUDIO_AUDIO_EXPORT_STORAGE_UNCONFIGURED | 503 | studio | No | Studio audio export storage is not configured. |
UPSTREAM_ASSET_STORAGE_ERROR | 503 | upstream | Yes | Audio asset storage failed. |
GENERATION_TIMEOUT | 504 | generation | Yes | Generation timed out. Please try again. |
UPSTREAM_TIMEOUT | 504 | upstream | Yes | Upstream request timed out. |