Errors

HTTP errors

Every error uses one shape:

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

HTTP	type	code
400	`invalid_request_error`	`invalid_request`, `unsupported_language`, `unsupported_model`
401	`authentication_error`	`unauthorized`
403	`permission_error`	`account_suspended`, `account_disabled`, `session_required`, `usage_limit_reached`, `model_access_denied`
404	`invalid_request_error`	`not_found`, `file_not_found`
409	`invalid_request_error`	`idempotency_conflict`, `transcript_not_ready`
413	`invalid_request_error`	`file_too_large`
429	`rate_limit_error`	`rate_limited`, `queue_full` (honour `Retry-After`)
5xx	`api_error`	`internal_error` (safe to retry with the same `Idempotency-Key`)

Include request_id when you contact support.

unsupported_language: only English is available today; multilingual support is planned.
usage_limit_reached, model_access_denied, queue_full: account limits. To raise them, talk to sales.

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, 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`	`file_id` missing or expired
`usage_limit_reached`	Longer than your remaining usage (talk to sales to raise it)
`internal_error`	Failed on our side after automatic retries; resubmit
`canceled`	You deleted the job before it finished

Retries

Retry 429 and 5xx with exponential backoff.
Send an Idempotency-Key header with POST /v1/transcripts so a retried request never creates a second job.

Get started

Guides

Operations

HTTP errors

Job errors

Retries

​HTTP errors

​Job errors

​Retries

HTTP errors

Job errors

Retries