Error handling

Dictation API error responses, status codes, and retry guidance.

Most errors return a JSON body with status, title, and detail fields:

{ "status": 401, "title": "Unauthorized", "detail": "Invalid API key" }

A second shape, with an error message and a machine-readable error_code, is used only for the errors Dictation raises while parsing the request itself, before the config is validated:

{ "error": "`config` is not valid JSON: Expecting property name enclosed in double quotes", "error_code": "bad_request" }

Read both when surfacing an error. In practice, checking detail first and falling back to error covers every case.

Status codes

HTTP	Body shape	Cause
400	error / error_code	A malformed request body: a missing or empty audio part, a missing config part or one sent after audio, or config that is not valid JSON
400	status / title / detail	A well-formed config that fails validation: an unknown field, a value out of range, or a field over its length limit
401	status / title / detail	Missing Authorization header, or an invalid API key
413	status / title / detail	Audio exceeded the size cap
415	status / title / detail	The audio part is not audio/wav or audio/pcm
429	status / title / detail	Rate limit exceeded
502	status / title / detail	Transcription upstream unavailable
503	status / title / detail	Server at capacity
504	status / title / detail	Transcription upstream timed out

Both auth failures return 401. A missing header gives detail: "Missing Authorization header", and a bad key gives detail: "Invalid API key".

A failed rewrite is not a failed request

The transcript rewrite is best-effort and is never allowed to fail the call. If the rewrite fails, the response is still 200, text still holds the verbatim transcript, llm_response is null, and llm_error says what went wrong:

llm_error	Meaning
timeout	The rewrite passed its 5-second internal deadline
error	The rewrite failed for another reason

Fall back to text when llm_response is null. Never treat a non-null llm_error as a failed request. In the Python SDK, result.final_text already does this: it returns the rewrite when there is one and the transcript otherwise.

Errors in the Python SDK

A failed request raises DictationError, which carries the pieces you need to decide what to do next:

Attribute	Meaning
status_code	The HTTP status from the table above
error_code	The machine-readable code, when the response carried one
retry_after	Seconds to wait, from the Retry-After header on a 429 or 503

import time

import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

try:
    result = aai.DictationTranscriber().transcribe_live("clip.wav")
except aai.DictationError as error:
    if error.retry_after:
        time.sleep(error.retry_after)
    raise RuntimeError(
        f"Dictation failed ({error.status_code}/{error.error_code}): {error}"
    )

retry_after is None when the response carried no Retry-After header, so fall back to your own backoff rather than assuming a value is present.

Retry guidance

• 429, 502, 503, and 504 are transient. Back off and retry.
• 400, 413, and 415 mean the request itself is wrong. Fix the audio or the config before retrying. See Audio requirements for the constraints.
• 401 is a credential problem. Retrying will not help.

A chunked upload cannot be replayed, so keep the audio in memory if you want to retry a failed request. Set the HTTP client timeout to 90 seconds; typical short clips respond in under a second.

Need help?

If you get stuck, contact our support team at [e-mail] or create a support ticket. Include the session_id from the response, or the failing request’s timestamp and endpoint if no response was returned, to help us look up your request.