Network failures happen. Idempotency lets you retry a request without being charged twice or generating a duplicate. Endpoints that cost a lot or start long-running work take a client-generated request ID — a UUID you create once and reuse on every retry of the same request.
Supported endpoints#
| Endpoint | Field | On reuse |
|---|---|---|
POST /v1/chat | usageRequestId | Optional. Ties the charge to an existing reservation. |
POST /v1/music | requestId | Required. Returns 409 DUPLICATE_REQUEST. |
POST /v1/osint/cases/{id}/runs | requestId | Required. Returns the existing run. |
Generating request IDs#
Use a version 4 UUID, generated once per logical operation. Store it alongside the job in your own database before sending the request, so a crashed worker can retry with the same ID.
REQUEST_ID=$(uuidgen | tr 'A-Z' 'a-z')const requestId = crypto.randomUUID()import uuid
request_id = str(uuid.uuid4())Behavior#
Music. If a track already exists for the requestId, the request is rejected with 409 and code DUPLICATE_REQUEST, and you aren't charged again. Fetch the existing track from List tracks.
OSINT runs. Sending the same requestId with the same goal, material and model returns the run that already exists, with 202. Sending the same ID with different input is an error (409) — generate a new ID when the input changes.
Request IDs are scoped to your account and never expire. Don't derive them from content (for example, a hash of the prompt) — two users or two genuine repeats would collide.