422: Idempotency-Key was already used

The error

{
  "error": {
    "kind": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used for POST /api/tos_links. Keys are shared across all endpoints, send a fresh key (ideally a UUID) with every new request.",
    "param": null,
    "request_id": "req_033xhsr1AZZxC8AOkK7y3W"
  }
}

Why it happens

Idempotency keys are global per environment. One key identifies one request, across all endpoints, for 24 hours. There are two ways to trip this:

1. Reusing a key on a different endpoint. Common during manual testing with keys like test. The message names where the key was first used.
2. Reusing a key with a different body on the same endpoint, for example retrying a create-customer call after editing a field. A retry must be byte identical. An edited request is a new request.

The behavior is deliberate. A route-independent cache would silently replay an unrelated response, so accidental reuse fails loudly instead.

The fix

Mint a fresh, unique key per request:

-H "Idempotency-Key: $(uuidgen)"

Reuse a key only to retry the exact same request after a timeout or a 5xx. That is the case the mechanism exists for, and it replays the original response safely.

Related responses

More detail: Idempotency.