Idempotency key format check

It verifies that the key is not empty, that it is long enough to be unique in practice, that it stays within a sane maximum length, and that every character is URL-safe so the key survives headers, logs and query strings without encoding surprises. You send one string, you get back a clear valid flag, the measured length, and a list of concrete issues when something is wrong.

Why idempotency keys need a format check

Idempotency keys exist so that a retried request — a payment submitted twice, an order created after a timeout — is processed once and only once. But the safety they promise depends on the key itself being well formed. A key that is too short collides with another client's key and silently deduplicates two different operations into one. A key that contains characters outside the URL-safe alphabet gets mangled somewhere between your client, a proxy, a log pipeline and the server, so the retry arrives with a different string than the original and is charged twice. A key that is empty is rejected outright by most APIs, often with a generic error that takes an afternoon to trace. Running the key through this idempotency key format check at the edge of your system catches all three failure modes at development time, in a test suite, or in pre-flight validation inside your own service, instead of in a reconciliation report weeks later.

What exactly is validated

The check applies the format guidance that payment processors and deduplication middleware document most often. First, the key must be a non-empty string; an empty key is an error, not a warning, because no server will accept it. Second, length: by default the key should be at least 16 characters, which is the floor below which uniqueness stops being plausible, and at most 255 characters, the ceiling most stores accept — both bounds are configurable per call. Third, the alphabet: every character must come from the RFC 3986 unreserved set — letters, digits, hyphen, dot, underscore and tilde. Those characters pass through HTTP headers, URL segments and log shippers without encoding, which is exactly where idempotency keys travel. When a character fails, the response lists each distinct offending character so you can see whether someone embedded a space, a slash or an emoji, and the issues array names the problem in machine-readable form: too_short, too_long or unsafe_characters.

Where the check fits in your stack

Most teams wire this into two places. The first is the client that generates keys: right after you build a key from a UUID, a timestamp and a user id, validate it once and log a warning if it fails, so a generator bug surfaces in staging instead of production. The second is contract testing: run a batch of keys from every integration you own through the endpoint in CI, so a library upgrade that changes encoding behaviour fails the build. The endpoint is deterministic and stateless — nothing is stored, no list of seen keys is consulted, and the same input always produces the same output — which means it is safe to call on real keys and cheap enough, at $0.002 per request, to run on every deploy. The same validation also runs free in your browser on this page, so a developer can paste a suspicious key during an incident and get the same answer the API would give.