Networks fail in the worst place: after the server acted but before you got the answer. An idempotency key makes the retry safe.
How it works
The client creates a unique key for one intended action and sends it with the request. The server stores the key with the result. If the same key arrives again, the server replays the stored result instead of acting again.
The IETF HTTPAPI working group is standardising this as the Idempotency-Key request header (draft 08, October 2026, not yet an RFC). It describes the key as “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” and recommends a UUID or similar random ID. The draft’s error cases:
| Situation | Status |
|---|---|
| Key missing where required | 400 Bad Request |
| Original request still in progress | 409 Conflict |
| Key reused with a different body | 422 Unprocessable Content |
AWS’s Builders’ Library makes the same point from the client side: “APIs with side effects aren’t safe to retry unless they provide idempotency.”
Why it matters
Retries with exponential backoff are standard practice, and many SDKs retry automatically. Without idempotency, a retry after a timeout can create two orders or two charges. With a key, retrying is safe whatever the first attempt did. That makes it a core tool for agents and scripts that buy, book or create things without a human watching.
On BroadNet Inference
BroadNet uses this pattern for buying hourly keys. POST /portal/keys/hourly takes a request_id in the JSON body, and the docs state that “Idempotency is required for money safety”:
curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
-H "Authorization: Bearer <portal-credential>" \
-H "Content-Type: application/json" \
-d '{"request_id":"order-20260920-001","label":"kiosk-1"}'
Reusing a request_id does not create or charge another key. After a timeout, a dropped connection, a 409 mint_in_progress or a 5xx, retry with the same request_id. A replay returns already_issued: true and the key’s alias; only the first successful response contains the raw key. The docs say: “Never generate a replacement id until the original result is known.”
BroadNet does not document an idempotency key for /v1/chat/completions or transcriptions. See error codes and retries for what to retry there, and rate limits for why blind retries can make a 429 worse.