Skip to main content

​
Error format

All errors share the same envelope. 
{
  "status": "error",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "model is required"
  },
  "request_id": "01JXXXXXXXXXXXXXXXXXXXXXXX"
}
error.details may carry additional structured context for some errors. Always log the request_id — include it when contacting support.

​
Error codes

CodeHTTPMeaningWhat to do
MISSING_API_KEY401API key missing or malformedCheck the header/query format — do not retry
INVALID_API_KEY401Key revoked or not foundUse a valid key — do not retry
INSUFFICIENT_BALANCE402Account balance is zeroTop up in the console
ACCOUNT_SUSPENDED403Account deactivatedContact support
INVALID_REQUEST400Missing or invalid parameters (including a missing or unknown model)Fix the request — do not retry
AUDIO_FORMAT_UNSUPPORTED400Format not one of wav / ogg / webmRe-encode the audio
AUDIO_TOO_LONG413Audio exceeds the duration limitSplit the audio
FILE_TOO_LARGE413File exceeds 50 MBCompress or split the file
RATE_LIMIT_EXCEEDED429Too many requests per minuteRetry with exponential backoff
CONCURRENT_LIMIT_EXCEEDED429Too many simultaneous WebSocket connectionsClose idle connections, then retry
TRANSCRIPTION_FAILED500Transcription pipeline errorRetry once; report with request_id if persistent
INTERNAL_ERROR500Unexpected server errorRetry once; report with request_id if persistent
SERVICE_UNAVAILABLE503Backend temporarily unavailableRetry with exponential backoff
CLIENT_DISCONNECTED—Client disconnected mid-stream (WebSocket only; appears in usage logs)—

​
Retry guidance

  • Safe to retry with backoff: SERVICE_UNAVAILABLE, RATE_LIMIT_EXCEEDED
  • Retry once: TRANSCRIPTION_FAILED, INTERNAL_ERROR
  • Do not retry: all 4xx — fix the request, top up, or contact support

​
WebSocket errors

Over WebSocket, errors are delivered as an error message (see Stream transcription); after an error message the server closes the connection.