Skip to main content
Every error response includes ok: false and a machine-readable code.

​
Error envelope

{
  "ok": false,
  "code": "AUTH_REQUIRED",
  "detail": "Authentication required.",
  "error": "Authentication required."
}

​
Reference

CodeStatusDomainRetry?Default message
BAD_REQUEST400commonNoThe request is invalid.
AUTH_INVALID_SESSION401authNoInvalid session.
AUTH_REQUIRED401authNoAuthentication required.
AUTH_SESSION_EXPIRED401authNoSession expired.
AUTH_USER_UNAVAILABLE401authNoUser not available.
BILLING_INSUFFICIENT_CREDITS402billingNoInsufficient credits.
AUTH_ADMIN_ACCESS_DENIED403authNoAdmin console access denied.
AUTH_ADMIN_ROLE_REQUIRED403authNoAdmin role required.
FORBIDDEN403commonNoForbidden.
RESOURCE_NOT_FOUND404commonNoResource not found.
CONFLICT409commonNoThe request conflicts with current state.
STUDIO_AUDIO_EXPORT_BLOCKED409studioNoStudio audio export is blocked by missing or stale clips.
STUDIO_AUDIO_EXPORT_INCOMPATIBLE_AUDIO422studioNoStudio audio export requires compatible PCM WAV clip audio.
STUDIO_AUDIO_EXPORT_NO_AUDIO422studioNoStudio audio export has no clip audio to export.
STUDIO_AUDIO_EXPORT_UNSUPPORTED_SOURCE422studioNoStudio audio export requires supported clip audio sources.
VALIDATION_ERROR422commonNoRequest validation failed.
GENERATION_NOT_READY425generationYesGeneration is not ready yet.
GENERATION_CONCURRENCY_EXCEEDED429generationYesYour plan’s concurrent generation limit was reached. Please retry shortly.
RATE_LIMITED429commonYesRate limit exceeded.
INTERNAL_ERROR500commonYesInternal server error.
STUDIO_AUDIO_EXPORT_FAILED500studioYesStudio audio export failed.
GENERATION_FAILED502generationYesGeneration failed.
GENERATION_INVALID_RESPONSE502generationYesGeneration service returned an invalid response.
UPSTREAM_ANALYTICS_ERROR502upstreamYesAnalytics service request failed.
UPSTREAM_BILLING_ERROR502upstreamYesBilling service request failed.
UPSTREAM_GENERATION_ERROR502upstreamYesGeneration service request failed.
UPSTREAM_GENERATION_SERVICE_ERROR502upstreamNoGeneration service request failed.
VOICE_CLONE_FAILED502voiceYesVoice clone failed.
VOICE_DESIGN_FAILED502voiceYesVoice design failed.
AUTH_CONFIG_MISSING503authNoAuthentication is not configured correctly.
DISPATCH_TIMEOUT503generationYesGeneration dispatch timed out before execution. Please try again.
GENERATION_CAPACITY_EXCEEDED503generationNoGeneration capacity is currently exhausted. Please try again shortly.
GENERATION_INTERRUPTED503generationYesGeneration was interrupted by a service restart. Please try again.
LLM_CONFIG_NOT_FOUND503upstreamNoLLM feature is not configured.
STUDIO_AUDIO_EXPORT_ASSET_READ_FAILED503studioYesStudio audio export could not read clip audio from storage.
STUDIO_AUDIO_EXPORT_ASSET_WRITE_FAILED503studioYesStudio audio export could not write the result to storage.
STUDIO_AUDIO_EXPORT_STORAGE_UNCONFIGURED503studioNoStudio audio export storage is not configured.
UPSTREAM_ASSET_STORAGE_ERROR503upstreamYesAudio asset storage failed.
GENERATION_TIMEOUT504generationYesGeneration timed out. Please try again.
UPSTREAM_TIMEOUT504upstreamYesUpstream request timed out.

​
Operational guidance

Authentication

Send API keys correctly and distinguish session-only account endpoints from API-key endpoints.

Rate limits

Retry concurrency, capacity, and timeout errors without overloading generation.

CLI troubleshooting

Map CLI exit codes to auth, quota, timeout, network, and dependency fixes.

Developer logs

Inspect failed requests, latency, request IDs, and generated cURL examples.