Reliability
Error Handling and Retries
Handle transcript failures, HTTP errors, and timeouts cleanly in a tight polling loop.
A robust short-clip loop has to handle three failure surfaces: the create call being rejected, the transcript itself failing, and the loop running out of time. This page covers all three.
Transcript statuses
Poll GET /v2/transcripts/{id} and branch on status:
| Status | What your loop should do |
|---|---|
| queued | Keep polling. |
| processing | Keep polling. This is the status the create call returns. |
| completed | Stop. Read text and the other result fields. |
| error | Stop. Read the error field for the reason; do not keep polling. |
Failed transcripts are not billed. When a job ends in error, fix the cause (most often an audio URL the service could not fetch, or a file that contains no usable audio) and create a new transcript.
HTTP errors on create
| Code | Error code | Meaning |
|---|---|---|
| 400 | unsupported_media_type | The upload sign request named a file that is not audio or video. |
| 400 | unknown_model | The model field is not a valid model id. Check GET /v2/models. |
| 400 | invalid_webhook_url | The webhook_url is not a public http(s) URL. Localhost, private ranges, and internal hosts are rejected. |
| 400 | (validation) | Neither audio_url nor upload_id was provided, or the body failed validation. |
| 402 | v2_billing_required | Free credit is used up (or the estimated cost exceeds what remains) and no API subscription is active. Add a payment method to continue. |
| 404 | not_found | The transcript or upload id does not exist or belongs to another account. |
| 409 | not_ready | You asked for sentences, paragraphs, word search, or subtitles before the transcript completed. |
| 413 | upload_too_large | The file exceeds the 5 GiB upload limit. |
Do not blindly retry a failed create call. Each successful create starts a new job, and every completed transcript is billed, so an aggressive retry loop can transcribe (and pay for) the same clip several times. Retry only after a network failure where no transcript id came back, and prefer checking GET /v2/transcripts first to see whether the job actually exists.
Timeouts and slow clips
- Always run the polling loop against a deadline, and treat exceeding it as a failure state in your UX.
- A clip can be slower than usual when the audio URL is slow to fetch or the service is under load. The transcript keeps processing server-side even after your loop gives up; polling the same id later can still find it completed.
- Transient network failures while polling are safe to retry immediately: GET /v2/transcripts/{id} is read-only.
- For pipelines where a bounded wait is awkward, register a webhook on the create call instead of polling; the notification arrives whenever the transcript finishes, fast or slow.
- If your clips regularly exceed a tolerable wait, move the workload to Realtime STT for live streaming, or accept the relaxed polling cadence of Pre-recorded STT.