Skip to main content
HTTP status: 400 · Title: “Idempotency key format invalid”

​
When it fires

The Idempotency-Key header contains a character outside the allowed set [A-Za-z0-9_\-:.] (letters, digits, underscore, hyphen, colon, period).

​
Why it happens

  • The key contains whitespace, a slash or a non-ASCII character.
  • Control characters (newlines, NULs) slipped in from a copy-paste.
  • An emoji or Unicode separator ended up in the key.
The allowlist is strict so that keys are always safe to log, store and compare.

​
How to fix

  • Use UUIDs (crypto.randomUUID() in Node, uuidgen in a shell). They always conform.
  • If you must derive the key from external input, sanitise it, for example key.replace(/[^A-Za-z0-9_\-:.]/g, ''), then check it is still unique.
See Idempotency.