Errors and limits

Every error code with its HTTP status, the request and job limits per key, the file size and length limits, and the supported languages.

Error body

Every error answers with the same body: success is false, and error holds a stable code, a plain-English message and details where there are any — for a bad request, the field at fault. meta.requestId is the same as the X-Request-Id header: quote it when you write to support. Branch on the code, never on the message.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request is invalid.",
    "details": {
      "field": "upload_id"
    }
  },
  "meta": {
    "requestId": "req_8b4c2e1f-6a9d-4f3b-9c7e-2d5a1b0f4e6c",
    "timestamp": 1792584000000
  }
}

Request errors

What a request answers with when it is refused.

HTTP	Code	When
400	`VALIDATION_ERROR`	The body or a parameter is invalid; details.field names it.
401	`INVALID_API_KEY`	The Authorization header is missing, malformed or names an unknown key.
402	`INSUFFICIENT_CREDITS`	Your available credits are zero.
403	`API_KEY_INACTIVE`	The key was deactivated in the console.
404	`NOT_FOUND`	The transcription or upload does not exist, belongs to another account, was deleted or has expired.
409	`UPLOAD_NOT_READY`	The file was not PUT to the upload URL yet, or the upload was already used by a transcription.
409	`NOT_READY`	A text format was requested before the transcription completed.
409	`NO_TRANSCRIPT`	A text format was requested for a failed transcription; create a new one to retry.
409	`IDEMPOTENCY_CONFLICT`	The same Idempotency-Key was sent with a different body.
413	`FILE_TOO_LARGE`	The uploaded file is larger than 350 MB.
415	`UNSUPPORTED_MEDIA`	The first bytes of the upload match none of the supported formats.
429	`RATE_LIMIT_EXCEEDED`	More than 120 requests a minute with one key; wait for Retry-After seconds.
429	`TOO_MANY_ACTIVE_JOBS`	5 transcriptions are already queued or processing for this key, or 10 for the account; Retry-After: 30.
500	`INTERNAL_SERVER_ERROR`	An error on our side; retry with the same Idempotency-Key.

Why a transcription failed

A transcription with status: failed carries one of these in error.code. A failed transcription costs nothing.

Code	When
`INSUFFICIENT_CREDITS`	The file is longer than your credits cover. Nothing was charged.
`FILE_TOO_LARGE`	The file at audio_url is larger than 350 MB.
`UNSUPPORTED_MEDIA`	The file's duration could not be read.
`AUDIO_TOO_LONG`	The audio is longer than 3 hours.
`DOWNLOAD_FAILED`	The audio_url is private, unreachable, answered with a non-2xx status or took longer than 10 minutes.
`TRANSCRIPTION_FAILED`	Processing failed on our side. Nothing was charged; retry the request.
`TRANSCRIPTION_TIMEOUT`	Processing did not finish within 60 minutes. Nothing was charged; retry the request.

Retrying

429: wait for the seconds in Retry-After, then send the request again. Too many transcriptions in progress clears in about 30 seconds, or as soon as one of them ends.
500 and network errors: retry after a short wait. A create sent with the same Idempotency-Key is never made twice, so the retry is safe.
Other 4xx: retrying the same request gets the same answer; fix the request first.
A failed transcription: TRANSCRIPTION_FAILED and TRANSCRIPTION_TIMEOUT are worth one more try with a new request; the others need a different file or more credits.

Limits

The same for every account; they are raised on request.

Limit	Value
Maximum file size	350 MB
Maximum audio length	3 hours
Requests per minute, per API key	120
Transcriptions in progress, per API key	5
Transcriptions in progress, per account	10
Retry-After when too many are in progress	30 seconds
Upload URL validity	1 hour
Result retention	72 hours
Idempotency-Key memory	24 hours
Idempotency-Key length, up to	64 characters
Minimum speakers_expected	1
Maximum speakers_expected	10
Redirects followed for audio_url	3
audio_url download time limit	10 minutes
Time before a transcription fails	1 hour
Webhook response timeout	10 seconds
Webhook delivery attempts	immediately, after 5 seconds, after 30 seconds
Webhook timestamp tolerance	5 minutes
Formats	mp3, wav, m4a, ogg, opus, flac, aac, wma, webm, mp4, mov, mkv, avi

Languages

Pass one of these codes as language, or leave it out to detect the language. A transcript reports the language in the same codes.

auto detects the language from the audio. It is the default.