DocsError codes

idempotency_key_reused

This `Idempotency-Key` was used before, for a request with a different body.

On this page
422HTTP 422 · Idempotency Key Reused

What it means#

This `Idempotency-Key` was used before, for a request with a different body.

Retry after fixing

Retrying unchanged will not help. Correct the cause, then send it again.

What causes it#

  • A key was reused across two genuinely different calls.
  • A retry mutated the payload — a regenerated timestamp or a re-ordered array is enough, because the guard hashes the whole body.
  • A key was derived from something not unique per operation, such as a user id.

How to fix it#

  • Generate a fresh key per logical operation — a UUID v4 is the right shape.
  • When retrying, send the byte-identical body you sent the first time. That is what makes the replay safe.
  • Never derive keys from mutable data.

The details object#

This code carries a details object with more than the message can say:

`{ key }` — the first 64 characters of the key that collided.

What the response looks like#

422 application/problem+json
{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This `Idempotency-Key` was used before, for a request with a different body",
    "details": { ... },
    "request_id": "7cb7f7862a82425d8e4c3fb8a497dfe6"
  },
  "type": "https://integrable.cloud/docs/errors/idempotency_key_reused",
  "title": "Idempotency Key Reused",
  "status": 422,
  "detail": "This `Idempotency-Key` was used before, for a request with a different body",
  "instance": "/api/agents/01a0652b-3713-7ea1-a6c9-2e895389ec34"
}

Branch on error.code, not on the message — the code is stable, the sentence is not. Log request_id either way.

Still stuck#

Quote the request_id from the response — hello@integrable.cloud. It is what lets us find the exact request. The full list of codes is at Error codes, and the conventions every endpoint shares are in Retries, versioning and limits.

Something unclear or missing? Tell us and we’ll fix it.