Error handling - AssemblyAI

Every error returns an RFC 9457 problem-details body with Content-Type application/problem+json. title is the stable identity of the error; detail explains this occurrence.

{ "status": 413, "title": "Audio Too Large", "detail": "audio duration 1300000 ms exceeds limit 1200000 ms" }

The SDKs raise SyncTranscriptError and expose title in snake case as the error code (error_code in Python, errorCode in JavaScript), so Audio Too Large becomes audio_too_large.

HTTP	`title`	Cause
400	`Bad Audio`	Malformed WAV, misaligned PCM, or missing `sample_rate`/`channels` for PCM
400	`Audio Too Short`	Audio below 80 ms on `/v1/transcribe`
400	`Bad Request`	Missing `audio` part, invalid config JSON, or field limits exceeded
401	`Unauthorized`	Missing or invalid API key
413	`Audio Too Large`	Duration > 20 minutes on `/v1/transcribe`, or > 120 s on `/v1/transcribe/live` (returned mid-upload); or file > 256 MB
415	`Unsupported Media Type`	Unsupported format, non-16-bit audio, or unsupported sample rate
429	`Too Many Requests`	Rate limit exceeded — retry after the `Retry-After` header
503	`Capacity Exceeded`	Server at its concurrency limit — retry after `Retry-After: 1`
503	`Service Unavailable`	Model still loading (cold start)
504	`Inference Timeout`	Request exceeded the server deadline: 30 s on `/v1/transcribe`; 300 s on `/v1/transcribe/live`, covering recording and transcription, or a live upload idle for 120 s
500	`Inference Error`	Internal model error

Retry guidance

429 and 503 are transient — retry after the Retry-After header (or a short backoff when absent).
400, 413, and 415 indicate a problem with the request itself — fix the audio or config before retrying. See Audio requirements for the constraints.
500 and 504 are safe to retry once; persistent failures warrant a support ticket.

Need help?

If you get stuck, contact our support team at support@assemblyai.com 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.