Errors

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

Code	HTTP	Meaning	What to do
`MISSING_API_KEY`	401	API key missing or malformed	Check the header/query format — do not retry
`INVALID_API_KEY`	401	Key revoked or not found	Use a valid key — do not retry
`INSUFFICIENT_BALANCE`	402	Account balance is zero	Top up in the console
`ACCOUNT_SUSPENDED`	403	Account deactivated	Contact support
`INVALID_REQUEST`	400	Missing or invalid parameters (including a missing or unknown `model`)	Fix the request — do not retry
`AUDIO_FORMAT_UNSUPPORTED`	400	Format not one of `wav` / `ogg` / `webm`	Re-encode the audio
`AUDIO_TOO_LONG`	413	Audio exceeds the duration limit	Split the audio
`FILE_TOO_LARGE`	413	File exceeds 50 MB	Compress or split the file
`RATE_LIMIT_EXCEEDED`	429	Too many requests per minute	Retry with exponential backoff
`CONCURRENT_LIMIT_EXCEEDED`	429	Too many simultaneous WebSocket connections	Close idle connections, then retry
`TRANSCRIPTION_FAILED`	500	Transcription pipeline error	Retry once; report with `request_id` if persistent
`INTERNAL_ERROR`	500	Unexpected server error	Retry once; report with `request_id` if persistent
`SERVICE_UNAVAILABLE`	503	Backend temporarily unavailable	Retry 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.

Reference

Endpoints

Limits & Errors

Error format

Error codes

Retry guidance

WebSocket errors

​Error format

​Error codes

​Retry guidance

​WebSocket errors

Error format

Error codes

Retry guidance

WebSocket errors