Idempotency

32Idempotency

The retry a caller cannot avoid: the request completed, the response was lost on the wire, and sending it again bills a second completion. Send an Idempotency-Key header on a non-streaming POST /chat/completions and the retry returns the stored first answer instead of running, and charging, again. The replay carries the response header idempotency-replayed: true and bills nothing.

curl https://rapidrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $RAPIDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8842-attempt-1" \
  -d '{
    "model": "google/gemini-3.6-flash",
    "messages": [{ "role": "user", "content": "Hi" }]
  }'

# send it again with the same key and body:
# same 200 response, header idempotency-replayed: true, nothing billed

The exact semantics:

• Same key, same body: the stored 200 replays, with idempotency-replayed: true.
• Same key, different body: 422 with code idempotency_mismatch. Silently answering with a response to a different question would be worse than failing, so use a fresh key per logical request.
• Same key while the first send is still running: 409 with code idempotency_in_flight. Retry after it finishes.
• Only 200s are stored. A failed call stays retryable with the same key.

Keys are scoped to your account, so they can never collide with another tenant's, and they live for 24 hours. On a streaming request the header is ignored: replaying a stream as a stored blob would change its shape mid-integration.