Guides/Retries and idempotency

Retries and idempotency keys

Retry a timed-out job creation safely with an Idempotency-Key, know which job errors are worth resubmitting, and back off on 429 and 5xx.

What is safe to retry

Reading a job is always safe, but remember the result is handed over once. Retrying a read you already succeeded at returns the same job with rows: null on every video.
Creating a job is not naturally safe. A timed-out create may well have succeeded, so retrying blind can queue the same video twice and charge twice.
A video that failed with internal_error or captions_fetch_failed is worth resubmitting; its retryable flag says so. One that failed with no_captions or video_unavailable will fail the same way.

Idempotency keys

Send an Idempotency-Key header on POST /v1. Repeating it with the same key inside 24 hours returns the original response, marked with an Idempotent-Replay: true header, instead of queueing the videos again, so a retry after a network timeout is free and harmless. Only a successful create is remembered: a refused one, say for credits, can be retried with the same key once the cause is fixed.

POST /v1
X-API-Key: tbx_live_...
Idempotency-Key: run-2026-09-03-vid-0417
Content-Type: application/json

NOTE

Derive the key from something stable in your own data, such as the run ID and the video ID, rather than a random value generated at call time. Reusing a key with a different body is a mistake rather than a replay, and answers 409.

Backoff

On 429 honour Retry-After. On 5xx retry three times with exponential backoff and jitter, then give up and record the failure rather than looping.

Was this page useful?Tell us what was missing

Videos without captions

/v1