For developers
Idempotency key generator
Make a UUID v4 for the Idempotency-Key header, with a ready curl line and our own retry rules explained next to it.
Free, no accountIn your browser
Shown in the curl line below. A new key is made every time you type.
Result
Nothing generated yet
Name the operation this key is for and one is made as you type.
What this is
This idempotency key generator makes a fresh UUID v4 in your browser for the exact Idempotency-Key header our API reads, with a ready curl line for the operation you name and the retry rules that key then follows.
An idempotency key exists so a request that is retried after a dropped connection cannot accidentally run twice: the first attempt's outcome is stored under the key, and a retry carrying the same key and the same body gets that stored outcome handed back rather than running again. It only ever has to be unique within your own account and within the one operation it names, which is why a fresh UUID v4 - effectively never repeated by chance - is the ordinary choice rather than anything that has to be coordinated with anyone else.
How to read the result
The curl line above sends the key as the exact header name our API reads, against the method and path parsed from whatever you typed. The table below it is the full set of outcomes that key can then produce: a replay on a matching retry, a 422 on a reused key with a changed body, a 409 on a retry that overlaps the first request still running, and a 400 on a key outside the length the API accepts at all.
"Verifying one of our webhooks" generates a key the same way for its own request-building and signature-testing examples, labelled local-testing-only, before moving on to the retry schedule, the API request builder and every documented error code.
Common mistakes
What goes wrong most often, and how to tell.
- Reusing a key across two different request bodiesAn idempotency key is a promise that a retry carries the exact same body as the request it is retrying. Reusing one for a second, different purchase is read as a mistake rather than a new attempt, and the API answers 422 instead of running the new body at all.
- Minting the real key on a page like this one, instead of in the client itselfA key copied from a browser tab only ever exists here - your own retry logic, running later and possibly on a different machine, has no way to reuse it. The key a real request relies on has to be generated by the same client code that sends the request, so its own retry can hand back the identical value.
Questions
What people ask about this tool.
- Exactly "Idempotency-Key", spelled that way - no other header name is treated as a retry key, and a request sent with no idempotency header at all is simply treated as brand new every single time it arrives, with nothing stopping a double charge if it is retried blindly.
- That is answered as a mistake, not a retry: the API responds 422 with the code "idempotency_key_reused" rather than running the new body, because the whole point of the key is that a retry replays the exact original request, not a different one wearing the same key.
- The second one answers 409 with the code "idempotency_in_progress" rather than running a second time in parallel or queueing silently behind the first - wait for the first request to actually finish, then retry with that same key and body.
- Only the ones that can spend money: ordering and renewing numbers, registering and renewing domains, and buying or resizing licences. A route that cannot charge the wallet ignores the header entirely, since nothing it does needs protecting against running twice.
- Open Developers in the dashboard and create an API key there; that is the only place a key our API accepts comes from, and it is what replaces $RHQ_API_KEY in the curl line above. This page never sees, holds or sends a real key - the idempotency key it makes is just the retry header that request carries.
- No. This page is for seeing the shape of the header and the curl line; real code has to call its own crypto.randomUUID() once per genuine operation, so that operation's own retry logic can reuse the exact value the first attempt generated rather than minting a new one it has already lost.
Use it from the API
The same check, as one request.