Errors

HTTP errors

Every error uses one shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_language",
    "message": "language 'de' is not supported; only English (\"en\", \"en-US\", ...) is available today. Multilingual support is planned.",
    "param": "language_code",
    "request_id": "req_01k6z..."
  }
}

HTTP	type	code
400	`invalid_request_error`	`invalid_request`, `unsupported_language`, `unsupported_model`; AirCaps Speaker ID-v1 (and `speaker_identification` on transcripts): `invalid_audio`, `audio_too_short`, `audio_too_long`, `no_enrolled_speakers`, `speaker_not_enrolled`
401	`authentication_error`	`unauthorized`
402	`invalid_request_error`	`insufficient_balance`
403	`permission_error`	`account_suspended`, `account_disabled`, `session_required`, `usage_limit_reached`, `model_access_denied`
404	`invalid_request_error`	`not_found`, `file_not_found`, `speaker_not_found`, `enrollment_not_found`
405	`invalid_request_error`	`method_not_allowed`
409	`invalid_request_error`	`idempotency_conflict`, `transcript_not_ready`, `diarization_not_ready`, `speaker_limit_reached`, `enrollment_limit_reached`
413	`invalid_request_error`	`file_too_large`
429	`rate_limit_error`	`rate_limited`, `queue_full` (honour `Retry-After`)
500	`api_error`	`internal_error`
503	`api_error`	`service_unavailable`: a brief capacity or dependency problem (honour `Retry-After`)
502, 504	`api_error`	`upstream_unavailable`, `upstream_timeout` (`request_id` is `null`)

Include request_id (also in the x-request-id header) when you contact support.

unsupported_language: only English is available today; multilingual support is planned.
insufficient_balance: your free hours and credits are used up. Add credits in the console (or turn on auto refill) to keep going.
usage_limit_reached, model_access_denied, queue_full: account limits. To raise them, talk to sales.
AirCaps Speaker ID-v1 reports problems with a clip in the response itself (it is synchronous): invalid_audio (not decodable or no audio), audio_too_short (under 0.5 s; enrollments under 1 s), audio_too_long (over 2 minutes), file_too_large (over 100 MB). These requests are not counted toward your usage.

Job errors

A transcript that fails has "status": "error" and an error object. None of these count toward your usage.

code	Meaning
`invalid_audio`	Not decodable, no audio stream, empty, or shorter than 0.1 s
`audio_too_long`	Longer than 10 hours
`file_too_large`	Larger than 5 GB
`download_failed`	`audio_url` could not be fetched (HTTP error, timeout, non-public address)
`file_not_found`	The uploaded file is missing or expired
`insufficient_balance`	Costs more than your remaining free hours and credits. Add credits and resubmit
`usage_limit_reached`	Longer than your remaining usage (talk to sales to raise it)
`internal_error`	Failed on our side after automatic retries. Resubmit; a `file_id` stays usable for 24 hours after upload

Deleting a queued or processing transcript cancels it: the DELETE response shows error.code canceled, no webhook is sent, and the ID then returns 404.

Retries

Retry 429, 500, 502, 503 and 504 with exponential backoff (for example 1 s, 2 s, 4 s … up to 60 s), honouring Retry-After when present.
Send an Idempotency-Key header with POST /v1/transcripts so a retried request never creates a second job. A retry with the same key and body returns the original transcript (200), even after it has finished.
Live streaming: on close code 1013, a connection that can’t be opened, one that drops without a close message, or one that goes quiet (no message for 30 seconds and no pong within 10 seconds of a ping), open a new session with backoff (for example 1 s, 2 s, 4 s … up to 30 s). See Live streaming.
Polling: call GET /v1/transcripts/{id} every 3–10 seconds, or use a webhook instead.
For large files, prefer an upload URL: the bytes go straight to storage, so a retry never re-sends them through the API.

Get started

Guides

Operations

HTTP errors

Job errors

Retries

​HTTP errors

​Job errors

​Retries

HTTP errors

Job errors

Retries