Core concepts

Idempotency

Every write request carries an Idempotency-Key, so a retry after a timeout returns the original result instead of doing — and charging for — the work twice.

How it works

Required on every POST, PATCH and DELETE except POST /quote. Missing: 400 IDEMPOTENCY_KEY_REQUIRED.
Any string up to 255 characters, unique per logical request. A UUID v4 is ideal.
Keys are scoped to the API key and remembered for 24 hours.
The first request’s response (status and body) is stored and replayed for repeats, marked with Idempotent-Replayed: true.
A repeat must be identical — same method, path and JSON body. Different content with the same key returns 409 IDEMPOTENCY_CONFLICT.

Safe retry

KEY=$(uuidgen)
curl …/v1/videos -H "Idempotency-Key: $KEY" -d @video.json   # times out
curl …/v1/videos -H "Idempotency-Key: $KEY" -d @video.json   # same generation, charged once

Outcomes

First attempt ended with	Repeating the same key
Success (2xx)	Replays the same response.
Client error (4xx, e.g. validation, insufficient credits)	Replays the same error. Fix the request and use a new key.
Rate or concurrency limit (429)	Not stored — the retry runs normally.
Server error (5xx) or crash	Not stored — the retry runs normally.
Still running	`409 IDEMPOTENCY_IN_PROGRESS` for up to 5 minutes; retry shortly.

Choosing keys

Generate the key when you decide to do the work and persist it with your own record (e.g. alongside the order it belongs to). Reuse it for every retry of that work; create a new key for new work.

Don’t derive keys from the request body — two users asking for the same prompt would share one generation.