Retries and idempotency

Networks fail. A request can time out after the API has already accepted it, and retrying a plain POST /v1/generations would then create, and charge for, a second generation. An Idempotency-Key header prevents that.

Idempotency keysCopy Anchor Link

Send a unique key, such as a UUID, with POST /v1/generations or POST /v1/account/topups. If a request with the same key and the same body arrives within 24 hours, the API returns the original response instead of doing the work again. Reusing a key with a different body fails with 409 idempotency_key_reused.

import { randomUUID } from "node:crypto";
import { RawFrame } from "@rawframe/sdk";

const rf = new RawFrame();

// Save the key with your own job record, so a retry after a crash or timeout reuses it.
const idempotencyKey = randomUUID();
const request = { model: "google/gemini-2.5-flash-image", prompt: "A red kite against a blue sky" };

const first = await rf.generations.create(request, { idempotencyKey });
const retry = await rf.generations.create(request, { idempotencyKey });
console.log(first.id === retry.id); // true: the retry returned the original generation

Generate the key once per piece of work and store it with your own record of that work, before the first attempt. Then a retry after a crash, a deploy or a timeout reuses it. A key made fresh on each attempt protects nothing.

What the SDKs retryCopy Anchor Link

The SDKs retry for you, up to 2 times by default (maxRetries / max_retries), with exponential backoff (0.5 s, 1 s, 2 s and so on, with jitter) or the server's Retry-After:

• Connection errors, timeouts, 408, 429 and 5xx on requests that are safe to repeat: reads, updates and deletes, and creates that carry an idempotency key.
• 429 only on other creates (uploads, webhook endpoints), because the API returns 429 before doing any work.

Every generations.create and account.createTopup / create_topup call sends an idempotency key: yours if you pass one, otherwise a new UUID for that call. So the SDK's own retries never duplicate work. Pass your own key for protection across process restarts.

Other errors (4xx besides 408 and 429) aren't retried: retrying won't change the answer.

Retrying failed generationsCopy Anchor Link

A generation that ended failed with error.retryable: true may work if you submit it again later, as a new request with a new idempotency key. See Errors.