Idempotency and safe retries
An Idempotency-Key lets the Gateway recognize a retry of an existing operation. It is required for asynchronous creation and optional for synchronous calls. Use it for paid synchronous calls when you may need to recover an uncertain outcome.
Save the identity before sending
Generate a unique value for each new logical operation and persist it before submission. Send it in the header:
Idempotency-Key: <your-saved-operation-key>
When retrying, preserve the same key, HTTP method, path, query, and body. The key identifies the operation within its organization, project, and logical method/path. Reusing it with different input or query parameters returns HTTP 409.
An operation still in progress can also return 409. Inspect the stable error code and follow the product's polling or recovery workflow; do not assume that every conflict means changed input.
What a retry preserves
| Operation | Guarantee |
|---|---|
| Paid operation | The original operation and its frozen price version remain in effect. |
| Asynchronous creation | A repeated submission returns the original job identity. |
| Synchronous call | The recorded financial result is preserved; the original response body is not guaranteed to be replayed. |
A new key requests a new operation and may incur a separate charge. It is not a way to recover the identity of earlier work.
Recover after a timeout
A timeout or disconnected client does not prove that execution failed to start. If an asynchronous submission response is lost, retry the same submission with the saved key and unchanged input. Once you have a job ID, read progress and results using the product's free read endpoints where provided.
For a synchronous call, use the original key to preserve its financial result. Do not silently create another paid operation to recover a lost response body.
Retry with backoff
Honor Retry-After when provided and increase the delay between attempts. The Gateway can retry safe idempotent reads internally, but does not automatically retry write requests. Your application should retry writes only with the original operation identity and according to the endpoint's documented behavior.
See errors and recovery for status-specific actions. The WHOIS batch guide shows the complete asynchronous submission, polling, pagination, and cancellation workflow.