---
title: "Send the same idempotency key when you · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/using-other-companies-apis/outgoing-idempotency-keys
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Send the same idempotency key when you retry a write

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Using other companies' APIs](https://agentwranglers.se/playbook/api-design/using-other-companies-apis.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- ID: API-76
- Level: Required
- Chapter: [Using other companies' APIs](https://agentwranglers.se/playbook/api-design/using-other-companies-apis)
- Rule: Create one idempotency key for each business action, store it with the action, and send the same key on every retry of that write.
- Risk: Money lost or taken twice
- How: A timeout does not tell you whether the provider did the work. Without a key, a retry can ship a parcel twice or send two invoices. Make the key from your own record, such as the order ID and the step, or store a random one before the first try. Send it in the header the provider documents, often `Idempotency-Key`. If the provider has no key, look up the result before a retry. Retry only as [retry with backoff and jitter](https://agentwranglers.se/playbook/api-design/reliability/retry-backoff) and [cap retries across the whole service](https://agentwranglers.se/playbook/operations/capacity-and-cost/retry-budget) say. Card charges follow [create each charge with an idempotency key](https://agentwranglers.se/playbook/payments/amounts-and-orders/idempotent-charge-creation).
- Check: Make the provider's fake do the work and then time out on the first call. The adapter retries with the same key, and the fake holds one shipment.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
async function bookShipmentOnce(order) {
  const key = `shipment-${order.id}`;
  return withRetries(() => fetch(`${CARRIER_URL}/v2/shipments`, {
    method: 'POST',
    headers: { 'idempotency-key': key, authorization: `Bearer ${CARRIER_KEY}` },
    body: JSON.stringify({ reference: order.id }),
    signal: AbortSignal.timeout(CARRIER_TIMEOUT_MS),
  }));
}
```

### Python example

```python
def book_shipment_once(order) -> httpx.Response:
    key = f"shipment-{order.id}"
    return with_retries(lambda: httpx.post(
        f"{CARRIER_URL}/v2/shipments",
        json={"reference": order.id},
        headers={"Idempotency-Key": key, "Authorization": f"Bearer {CARRIER_KEY}"},
        timeout=CARRIER_TIMEOUT,
    ))
```

## Sources

- [Expired IETF draft on the Idempotency-Key HTTP Header Field](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)

## Related rules

- [Retry with backoff and jitter](https://agentwranglers.se/playbook/api-design/reliability/retry-backoff) in API design
- [Cap retries across the whole service](https://agentwranglers.se/playbook/operations/capacity-and-cost/retry-budget) in Operations
- [Create each charge with an idempotency key](https://agentwranglers.se/playbook/payments/amounts-and-orders/idempotent-charge-creation) in Payments

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/api-design/using-other-companies-apis/outgoing-idempotency-keys">Agent Wranglers API design playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Wrap each outside API in one adapter](https://agentwranglers.se/playbook/api-design/using-other-companies-apis/one-adapter-per-api)
- Next: [Stay under their rate limits](https://agentwranglers.se/playbook/api-design/using-other-companies-apis/respect-their-limits)
- [Using other companies' APIs](https://agentwranglers.se/playbook/api-design/using-other-companies-apis)