BroadRouter
Get started

Idempotency key

Updated

An idempotency key is a unique value, usually a random ID such as a UUID, that a client attaches to a request that changes state, such as a payment or a purchase. If the same request is sent again with the same key, the server returns the original result instead of performing the action twice.

Also called: Idempotency-Key header, idempotency token, idempotent request, idempotent retry

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.

Questions

When should I generate a new idempotency key?

Only for a new intended action. Reuse the same key for every retry of one action, and do not create a new one until you know the outcome of the first attempt.

Do LLM chat completion requests need an idempotency key?

Generating text has no lasting side effect, so a repeated chat request usually just costs tokens again. The key matters for calls that charge money or create resources. BroadNet documents it only for hourly-key purchases, not for chat completions.

What happens if I reuse a key with a different request body?

The IETF draft says the server should reject it with 422 Unprocessable Content, because the key is already tied to a different request.

Read as MarkdownAsk ChatGPTAsk ClaudeAsk Perplexity