Idempotency

Send an Idempotency-Key header with any value unique to the operation. If the same key arrives again, the gateway does not run the request a second time.

curl https://api.opinference.com/v1/images/generations \
  -H "Authorization: Bearer $OP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-hero-image" \
  -d '{"model": "black-forest-labs/flux-1-schnell", "prompt": "a brass bar", "width": 512, "height": 512}'

How keys are scopedCopy Anchor Link

• A key is remembered for 24 hours.
• Keys are scoped to the API key that sent them. Two API keys can use the same value without colliding.
• The body is not compared. Reusing a value with a different body is treated as a repeat of the first request, so use a new value for each distinct operation.

Media jobs: the retry returns the jobCopy Anchor Link

A repeated submit returns 200 with the original job instead of 202 with a new one. The job id and generation_id are the same, so a retry after a network error is always safe. Use one key per job.

Chat: the retry is refusedCopy Anchor Link

A chat completion is not replayed. A repeat returns 409 idempotency_conflict, which tells you what happened to the first request:

{
  "error": {
    "code": "idempotency_conflict",
    "message": "idempotency conflict: generation gen_... is completed",
    "generation_id": "gen_...",
    "state": "completed",
    "usage": {"input_tokens": 70, "output_tokens": 40},
    "cost": {"billing_usd": 0.0000054}
  }
}

state is in_flight, completed or failed. usage appears once the first request has finished, and cost appears when it was billed.

If the first request failed before any reply reached you, the key is released, and a retry with the same key runs normally.

What is checked firstCopy Anchor Link

The key is checked after authentication, the rate limit and the spend check. So a repeat can be refused before the key is looked at:

• 402 insufficient_credit when your account has no prepaid credit left.
• 402 budget_exceeded when the request would cross a spend cap. This includes a repeat of a request that has already succeeded, so a replay at the cap gets 402, not the job or the 409.
• 429 rate_limited when the key is over its rate limit.