Idempotency

A request whose answer never arrives may or may not have run. To make a POST safe to send again, give it an idempotency-key header and retry with the same key: the work is done once, however many attempts it takes. Reads need no key: retry them with max_age set to the seconds since the first attempt, and the retry is served free from the cache.

How it works

• Every POST accepts the header. Use a new random value for each new request (a UUID is ideal), up to 255 printable ASCII characters, and reuse it only to retry that same request.
• Keys belong to your account and to one route, and are kept 1 day (15 minutes for an answer that shows a secret). After that, a retry doesn't run again: it answers idempotency_key_reused with details.reason answer_expired. The request ran, so check what it did before you send it again under a new key.
• The first request with a key runs normally. Once it has succeeded, a retry with the same key and the same body doesn't run again: it answers with the first request's status and the resource's current state (a job created then is shown as it is now), with the header idempotent-replayed: true. Routes that show a secret once (a new key or webhook endpoint, a rotated secret) answer exactly what they answered the first time. A key's previous secret, after a rotation, never gets such an answer back: idempotency_key_reused.
• The body is compared after parsing, so key order and whitespace don't matter.

With the TypeScript SDK, every POST carries a key, reused for its automatic retries. Over plain HTTP, send a new key with every POST and reuse it, with the same body, whenever you retry that request.