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.
All pages
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.
- 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.
- 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.
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"
}