Platform / Errors and retriesSign in Get an API key

Errors and retries

Every error has a stable code, an HTTP status and a request ID. Here is what each one means and when to retry.

Error shape

JSON

{
  "error": {
    "code": "unsupported_mode",
    "message": "The requested mode is not supported for this language.",
    "detail": "mode"
  }
}

code is stable — branch on it.
message is for people and may be reworded.
detail, when present, names the field or capability involved.
Every response carries an x-request-id header. Include it when you contact support.

When to retry

Status	Retry?
`429`	Yes, after the `Retry-After` header's seconds.
`503`	Yes, after `Retry-After`. For synchronous requests use a new idempotency key.
`504`	Synchronous only: retry with a new idempotency key, or use the asynchronous flow.
`500`	Yes, with backoff and the same idempotency key.
`4xx`	No — fix the request first.

The SDKs retry 429 and 503 for you, honouring Retry-After.

Idempotency

Send an Idempotency-Key header with POST /v1/transcriptions and POST /v1/audio/transcriptions. Repeating a request with the same key and the same body returns the original transcription instead of starting a new one — and charging twice. Reusing a key with a different body returns 409 idempotency_conflict.

All error codes

Code	HTTP	Message
`unauthorized`	401	Missing or invalid API key.
`forbidden`	403	This key cannot access this resource.
`not_found`	404	Resource not found.
`invalid_request`	422	The request is invalid.
`unknown_parameter`	422	The request contains an unknown parameter.
`unsupported_language`	422	The requested language is not supported.
`unsupported_mode`	422	The requested mode is not supported for this language.
`capability_unavailable`	422	The requested capability is not available yet.
`upload_incomplete`	409	The upload has not been completed.
`result_not_ready`	409	The transcription has not finished.
`idempotency_conflict`	409	The idempotency key was already used with a different request.
`audio_too_large`	413	The upload exceeds the size limit.
`capacity_unavailable`	503	Transcription capacity is temporarily unavailable.
`insufficient_credits`	402	Available credit is insufficient for this request.
`rate_limited`	429	Too many requests. Retry after the indicated time.
`spend_limit_reached`	429	The daily spending limit for this organization has been reached.
`too_many_queued`	429	Too many transcriptions are waiting for this organization.
`audio_decode_failed`	415	The audio could not be decoded.
`audio_too_long`	413	The audio exceeds the duration limit.
`too_many_channels`	422	The audio has more channels than supported.
`upload_rejected`	422	The upload could not be verified.
`content_deleted`	410	The content of this transcription has been deleted.
`conflict`	409	The resource is in a state that does not allow this operation.
`timeout`	504	The transcription did not finish within the response time limit.
`organization_disabled`	403	This organization is disabled.
`transcription_failed`	500	The transcription could not be completed.
`internal_error`	500	An internal error occurred.

Coming-soon capabilities

Requesting something that is on the roadmap but not live — language: "auto", timestamps: "word" — returns 422 capability_unavailable with detail naming it, for example language.auto. Nothing is ever silently ignored or approximated.