Idempotency and retries

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.