---
title: Idempotency and retries
description: Retry mutations safely and respect the account rate limit.
---

Address create/update/delete and shipment create/update/book/cancel require an `Idempotency-Key` header: nonempty, at most 255 characters after trimming. Service discovery, price preview, and reads do not require it.

## Retry a mutation

- Generate a unique key for each intended mutation. After an uncertain response, retry the same request with the same key. Stored successful outcomes replay without repeating the mutation; each attempt receives a new `requestId`.
- Keys are scoped to the account and operation. Reusing one for different validated input returns `409 IDEMPOTENCY_KEY_REUSED`.
- Use a new key for a changed request. Booking's `PRICE_CHANGED` conflict is stored: review `errors.price`, then use a new key to accept it.
- If booking dispatch returns `503 SERVICE_UNAVAILABLE`, acceptance may already be committed. Retry with the **same key** to resume queue dispatch.

## Rate limits

All keys and endpoints share a fixed-window limit of **120 requests per minute per account**. After `429 TOO_MANY_REQUESTS`, wait the whole seconds in `errors.retryAfterSeconds`. A rate-limit rejection does not execute the endpoint mutation. An unavailable rate-limit store returns `503 SERVICE_UNAVAILABLE`.