Idempotency

Send an X-Idempotency-Key header on generation requests to make retries safe: if the same key is submitted again, the stored 202 response is replayed verbatim and nothing is re-charged or re-generated. Use it whenever a timeout or network failure leaves you unsure whether a request went through.

Usage

The key is any string up to 128 characters (longer returns 400) and is scoped to your API key — two different API keys can use the same value independently. Pick something that uniquely identifies the operation on your side and reuse it on every retry of that operation:

# Same key on every attempt — curl retries transient failures itself
curl -X POST https://api.rendergrid.io/api/public/v1/images/generate \
  --retry 3 \
  -H "Authorization: Bearer rg_live_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-8412-cover-v1" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "a studio product shot of a ceramic mug on a marble surface"
  }'

Replay semantics

Once a request with a given key is accepted, submitting the same key again returns the original 202 body — same creation id, same cost — with no new charge. Replays are durable: the stored response is returned even long after the original request.

Concurrent requests

If a second request arrives while the first with the same key is still being processed, it returns 429 ERR_QUOTA_EXCEEDED with details.reason = "idempotency_in_flight" — wait and retry.

Failed requests

A request that fails releases its idempotency key, so retrying with the same key issues a fresh attempt. Combined with the automatic refund on failure (see Errors), a retry loop with a stable key never double-charges.