Skip to main content
New Send an Idempotency-Key header on any POST request that takes a JSON body to make it safe to retry. If the first attempt already succeeded, the retry returns that original response instead of creating a second record or sending a second message. File uploads are the exception — they take form data, and the header has no effect there.
Generate a unique value per operation — a UUID is a good choice. The header is optional: a request without it behaves exactly as it always has.

​
Retrying

Send the identical request — same endpoint, same body — with the same key. The replayed response carries an Idempotency-Replay: true header so you can tell it apart from a fresh one. Use a new key whenever you mean to perform a new operation, even a similar one. Reusing a key with a changed body is rejected rather than treated as a retry, so a key is bound to exactly one request. Keys are scoped to your organization and last 24 hours. After that the same value can be used again for a new operation.

​
While a request is still running

If you retry before the original request has finished, the retry returns 409 and the original keeps running. Wait, then retry again to collect the result. A request that fails releases its key immediately, so you can retry it with the same key. When an error tells you to use a new key, use one — retrying with the original returns the failed attempt instead of starting a new one.

​
Errors

See Errors for the full catalog.

​
Domain registration and renewal

Registering a domain (POST /v1/domain-registrations) and renewing one (POST /v1/domains/{id}/registration/renew) move money, so the header is required there. Omitting it returns 400. See Register a Domain via the API.
Last modified on August 29, 2026