Invalid Idempotency Key

invalid-idempotency-key · 400

The Idempotency-Key header came with a value the API can't use, so the operation didn't run.

The value was empty or longer than 255 characters. errors[] names the header with field: "Idempotency-Key".

Besides the members every error carries, this type adds errors.

Common causes

  • The header was set from a variable that was empty at the time.
  • The key was built from a long payload rather than from an identifier.

How to fix the call

  • Send a UUID as the key. It is short, unique, and needs no coordination.
  • Make the key once per operation and reuse it on every retry of that operation. A key made fresh on each retry defeats the purpose.
  • Leave the header out rather than sending it empty.

Example response

json
{
  "type": "invalid-idempotency-key",
  "title": "Invalid Idempotency Key",
  "detail": "Idempotency-Key must be a non-empty string of at most 255 characters. A UUID is recommended.",
  "errors": [
    {
      "field": "Idempotency-Key",
      "message": "must be between 1 and 255 characters",
      "value": ""
    }
  ],
  "requestId": "req-1785231000000-4f7b2c9ae",
  "timestamp": "2026-07-28T09:30:00.000Z",
  "path": "/v1/projects/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401/services",
  "method": "POST",
  "instance": "POST /v1/projects/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401/services",
  "status": 400,
  "docs": "https://ghaym.me/docs/errors/invalid-idempotency-key"
}