Skip to content

invalid_idempotency_key

HTTP/1.1 400 Bad Request
{
  "error": {
    "type": "idempotency_error",
    "code": "invalid_idempotency_key",
    "message": "Idempotency-Key must be at most 255 characters.",
    "param": "Idempotency-Key",
    "docs_url": "https://docs.patomic.dev/errors/invalid-idempotency-key",
    "request_id": "…",
    "suggestion": "Use 1–255 ASCII characters such as a UUIDv4. Store the same key alongside your client's intent so retries reuse it."
  }
}

What it means

The Idempotency-Key header was present but didn’t pass validation.

What causes it

Too long. > 255 characters.
Empty. Header sent but the value is the empty string.

How to fix

Use a UUIDv4 or similar, generated once per logical request and reused on every retry of that request. The simplest correct implementation:

import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID();   // 36 chars, well under 255

Persist the key alongside your client’s intent before the call, so a client crash mid-flight is still replayable on restart.