Guides/Retries and idempotency

Retries and idempotency

How to retry without paying twice for the same video.

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 a null result.
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 job that failed with internal_error is worth retrying. One that failed with no_captions or schema_invalid will fail the same way.

Idempotency keys

Send an Idempotency-Key header on any create. Repeating a create with the same key inside 24 hours returns the original job instead of making a new one, so a retry after a network timeout is free and harmless.

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