Idempotency

Эта страница есть на русском

Esta página también está en español

此页面也有中文版

Why you need an idempotency key

The connection can drop after your request reached us but before you got the response. You do not know whether the request was accepted. Sending it again without a key means buying a second image.

Without a key

You sent a request—the connection dropped, no response.
You sent it again.
You got two images and two charges.

With an idempotency key

You sent a request with a key—the connection dropped.
You sent the same request with the same key.
You got the same id and one charge.

How to use it

Pass the X-Idempotency-Key header in the generation request. A UUID or an operation number from your system will do: a non-empty string of at most 128 characters, otherwise 400 ERR_INVALID_REQUEST.
A new image takes a new key. A repeat of the same request keeps the previous key.
Save the key and the exact request body before sending: you need them for a retry.
An idempotency key is scoped to one API key. A different API key, even of the same account, treats the operation as new.
The key does not compare the request body. If you send a different prompt with the same key, the previous response comes back, and the prompt changes nothing. Use a new key for a new operation.

Without the header there is no protection against repeated execution.

What a retry returns

If the first request has already been accepted, a retry with the same key returns the same 202 response: the same id, status, task_id, and cost. There will be no new image and no new charge.

This is the saved response to the submission, not the current state: it may still say queued even when the image is already ready. Always take the current status from GET /creations/{id}.

An example with retries

The code below makes at most three attempts, sets timeouts, waits longer each time, and obeys Retry-After. The idempotency key is created once per operation and does not change between attempts.

The curl example sends the request once. If the result is unknown, repeat it manually with the same key and body.

What to do if…

Situation	What to do
A timeout or a dropped connection, no response	Repeat the request with the same key and the same body
A `429` response: the first request is still being accepted	The response has `details.reason: idempotency_in_flight`. Wait for `Retry-After` and repeat with the same key
A `400`, `402`, or `404` response	The request was not accepted. Remove the cause and repeat with the same key
A `5xx` response	Repeat with the same key, limiting the number of attempts. `500` does not say whether the request was accepted
A `202` arrived, and then the task became `failed`	The old key will not restart the task. A new attempt needs a new key: it is a new paid operation, and the previous one is refunded automatically
You need a second image	A new request with a new key

A failed request is free: the amount goes straight back to your balance.

How long a key is stored

Saved responses are kept for 30 days. After that the record may be deleted, and the same key will start a new paid generation. Keep your own link “your operation → task id” and do not use old keys as a way to look things up.

An idempotency key does not give an unconditional guarantee during service failures. Send the requests of one operation one after another, limit the number of attempts, and keep your own records. If after retries it is still unclear whether the request was accepted, look at the request history or contact support—before sending it with a new key.

Frequently asked questions

Do I need an idempotency key for every request?

Yes, for every generation request: without one, a retry after a dropped connection can create a second image and a second charge.

Can I use one key for different images?

No. One key is one operation. If you send a new request with the old key, the response to the first one comes back, and no new image is created.

What happens if the key is longer than 128 characters?

The API answers 400 ERR_INVALID_REQUEST. Use a UUID or a short operation number.

# Requires bash, curl, and uuidgen. The key is created once per operation.
IDEMPOTENCY_KEY="$(uuidgen)" || exit 1
curl --fail-with-body --max-time 30 \
  -X POST https://api.rendergrid.io/api/public/v1/images/generate \
  -H "Authorization: Bearer $RENDERGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "A ceramic mug on marble, soft window light"
  }'

import os
import random
import time
import requests

API = "https://api.rendergrid.io/api/public/v1"
KEY = os.environ["RENDERGRID_API_KEY"]


def submit(
    payload: dict, operation_key: str, max_attempts: int = 3
) -> dict:
    headers = {
        "Authorization": f"Bearer {KEY}",
        "X-Idempotency-Key": operation_key,
    }
    for attempt in range(max_attempts):
        last = attempt + 1 == max_attempts
        delay = 2 ** (attempt + 1) + random.random()
        try:
            resp = requests.post(
                f"{API}/images/generate",
                headers=headers, json=payload, timeout=(5, 30),
            )
        except (requests.Timeout, requests.ConnectionError):
            if last:
                raise
        else:
            if resp.status_code == 202:
                return resp.json()
            try:
                details = resp.json()["error"].get("details") or {}
            except (ValueError, KeyError, AttributeError):
                details = {}
            retryable = (
                resp.status_code == 429
                or resp.status_code >= 500
                or details.get("retryable") is True
            )
            blocked = details.get("reason") == "burst_block"
            if blocked or not retryable or last:
                raise RuntimeError(resp.status_code, resp.text)
            wait = resp.headers.get("Retry-After", "")
            if wait.isascii() and wait.isdigit():
                delay = max(delay, int(wait))
        time.sleep(delay)


payload = {
    "model": "nano-banana-pro",
    "prompt": "A ceramic mug on marble, soft window light",
}
creation = submit(payload, operation_key="order-8412-cover-v1")
print(creation["id"])

// Node.js 22+, .mjs file
const API = "https://api.rendergrid.io/api/public/v1";
const KEY = process.env.RENDERGRID_API_KEY;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function submit(payload, operationKey, maxAttempts = 3) {
  const body = JSON.stringify(payload);
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const last = attempt + 1 === maxAttempts;
    let delay = (2 ** (attempt + 1) + Math.random()) * 1_000;
    let resp;
    try {
      resp = await fetch(`${API}/images/generate`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${KEY}`,
          "Content-Type": "application/json",
          "X-Idempotency-Key": operationKey,
        },
        body,
        signal: AbortSignal.timeout(30_000),
      });
    } catch (error) {
      const network = error instanceof TypeError;
      if (!network && error.name !== "TimeoutError") throw error;
      if (last) throw error;
    }
    if (resp) {
      if (resp.status === 202) return resp.json();
      const text = await resp.text();
      let details;
      try {
        details = JSON.parse(text)?.error?.details;
      } catch {
        details = undefined;
      }
      const retryable = resp.status === 429 || resp.status >= 500 || details?.retryable === true;
      const blocked = details?.reason === "burst_block";
      if (blocked || !retryable || last) {
        throw new Error(`HTTP ${resp.status}: ${text}`);
      }
      const wait = resp.headers.get("Retry-After");
      if (wait && /^[0-9]+$/.test(wait)) {
        delay = Math.max(delay, Number(wait) * 1_000);
      }
    }
    await sleep(delay);
  }
}

const payload = {
  model: "nano-banana-pro",
  prompt: "A ceramic mug on marble, soft window light",
};
const creation = await submit(payload, "order-8412-cover-v1");
console.log(creation.id);

01Why you need an idempotency key

02How to use it

03What a retry returns

04An example with retries

05What to do if…

06How long a key is stored

FAQFrequently asked questions

Why you need an idempotency key

How to use it

What a retry returns

An example with retries

What to do if…

How long a key is stored

Frequently asked questions