---
title: "What is an idempotency key? Safe API retries explained"
description: "An idempotency key is a unique client-made ID sent with a request so a retry cannot repeat its effect, like a second charge. How it works, plus the IETF header."
url: https://broadrouter.com/glossary/idempotency-key/
lang: en
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

# Idempotency key

Updated 2026-11-14

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](https://broadrouter.com/glossary/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](https://broadrouter.com/blog/hourly-llm-api-key-explained/). `POST /portal/keys/hourly` takes a `request_id` in the JSON body, and the docs state that “Idempotency is required for money safety”:

```bash
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](https://broadrouter.com/guides/errors-and-retries/) for what to retry there, and [rate limits](https://broadrouter.com/glossary/rate-limit/) 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.

## See also

-   [Exponential backoff](https://broadrouter.com/glossary/exponential-backoff/) (term)
-   [Rate limit](https://broadrouter.com/glossary/rate-limit/) (term)
-   [API key](https://broadrouter.com/glossary/api-key/) (term)
-   [Concurrency](https://broadrouter.com/glossary/concurrency/) (term)
-   [BroadNet Inference error codes and when to retry](https://broadrouter.com/guides/errors-and-retries/) (guide)
-   [Lock API keys to your servers with IP allow-lists](https://broadrouter.com/guides/api-keys-ip-allow-lists/) (guide)
-   [Long-running agents: timeouts, retries and checkpoints that hold](https://broadrouter.com/blog/long-running-agents-timeouts-retries/) (article)
-   [Hourly LLM API key: a flat price per hour, explained](https://broadrouter.com/blog/hourly-llm-api-key-explained/) (article)

Try it on your real workload. New accounts start with $5 of credit for Gemma and transcription. DeepSeek, GLM and Qwen3.8 need a top-up.

[Get started](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=glossary-idempotency-key&utm_content=page-cta) ·

**Sources**

-   [IETF HTTPAPI, The Idempotency-Key HTTP Header Field (Internet-Draft)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)
-   [AWS Builders' Library, Timeouts, retries and backoff with jitter (idempotency tokens)](https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter)
-   [BroadNet Inference API reference, hourly keys (request\_id idempotency)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=glossary-idempotency-key&utm_content=sources#hourly-keys)
