Safe retries

Idempotency

Every POST requires Idempotency-Key. It prevents a timeout or repeated click from creating duplicate provider work, duplicate quota settlement, or multiple upload declarations.

Rules

Length: 8–128 characters.
Allowed shape: starts with a letter or digit, followed by letters, digits, period, underscore, colon, or hyphen.
Generate it once for one logical action and persist it until that action reaches a terminal result.
Use a new value when the input or intended action changes.
Scope is the owning API key, so identifiers do not cross customer keys.

Recommended generation

// Node.js
const idempotencyKey = crypto.randomUUID();

# Python
idempotency_key = str(uuid.uuid4())

Retry decision table

Situation	What to do	Idempotency key
Connection failed before a response	Retry with exponential backoff and jitter.	Reuse the same key.
HTTP 409 conflict while processing	Wait, then retry or poll the relevant job.	Reuse the same key.
HTTP 429 rate limited	Honor the delay in your application and back off.	Reuse the same key.
HTTP 503 provider unavailable	Back off; the confirmed non-chargeable failure does not consume quota.	Reuse the same key.
Validation or authentication error	Fix the request or credential before retrying.	Reuse only if the logical payload is unchanged; otherwise create a new key.
User edits the prompt or input file	Treat it as a new logical operation.	Create a new key.
Successful response was lost	Retrying retrieves the retained encrypted synchronous result during the idempotency window.	Reuse the same key.

Concurrent requests

If two identical requests arrive together, one may reserve execution while the other receives 409 conflict. Do not change the key to bypass that state; wait and retry the same operation.