Idempotency
Retries never double-bill.
Every write requires an Idempotency-Key header. Retrying with the same key and body replays the original result instead of running again.
http
Idempotency-Key: 3f8c1a2e-9b4d-4c6a-8e1f-2a7b9c0d1e2fSemantics
| Situation | Result |
|---|---|
| New key | The request runs; the response is stored. |
| Same key + same body, completed | The stored response is replayed — no second run, no second billable unit. |
| Same key + same body, still in flight | 409 idempotency_in_progress — retry shortly. |
| Same key + different body | 422 idempotency_conflict — use a fresh key. |
This is distinct from project-identity dedup. Re-uploading the same project file is deduplicated by its content hash regardless of the Idempotency-Key; the Idempotency-Key handles "same request retried." The SDKs generate and reuse a key per logical request for you.