Reliability: fallback models and safe retries

Models sometimes don't answer. Your app shouldn't go down with them.

5 minLesson 4 of 90 of 2 steps

Every model sometimes doesn't answer: heavy load, maintenance, a passing error. A good app plans for this. IranRouter has a few simple tools for it.

Fallback models

Beside model you can send a models list. If the first can't answer and nothing has been sent yet, the next is tried.

JSON
{
  "model": "anthropic/claude-sonnet-4.6",
  "models": ["deepseek/deepseek-v4-flash"],
  "messages": [{"role": "user", "content": "Hello"}]
}

The chain is at most three models, counting model itself. A switch is never hidden: the log shows the models tried and which one answered, and you pay only for that one.

Once the first byte of an answer has arrived, there's no fallback; changing models mid-answer makes something nobody wants.

Safe retries

Say you send a request and the connection drops. You don't know whether it arrived. Send it again and you might pay twice. The Idempotency-Key header solves this:

Shell
curl https://iranrouter.com/v1/chat/completions \
  -H "Authorization: Bearer ir-..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4-flash", "messages": [{"role": "user", "content": "Hello"}]}'

Send the same key again and the same answer comes back from memory, not charged again. While the original is still running you get a 409. This header works only on non-streaming requests.

Long jobs

For work that takes minutes, use the async route rather than holding a connection open. Send the same body to /v1/async/ plus the path, get a job id at once, and read the result later.

Shell
curl https://iranrouter.com/v1/async/chat/completions \
  -H "Authorization: Bearer ir-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4-flash", "messages": [{"role": "user", "content": "Write a report"}]}'

For bulk work there's POST /v1/batches: a JSONL file of requests runs in the background and the results come back as a file. A batch has no discount: each line is charged what the same request costs sent directly; it's a convenience, not a lower price.

A pattern to follow

  1. Give every critical model a fallback.
  2. Retry on 429 and 503 with a growing delay, and honour retry-after.
  3. Send Idempotency-Key on requests that must not run twice.
  4. Watch for the Deprecation and X-IranRouter-Successor headers on older models.
See the status page to know which models are steady; every figure there states its source.

Try a chain0 of 2 steps

  1. Send a request with a models list and see the answer.
  2. Open that request's row in the logs and read its chain.

What you learned

  • models gives fallbacks, and only the model that answered costs anything.
  • Idempotency-Key makes retries safe.
  • Long jobs go to the async route.
Beyond text: images, audio, video, OCR and embeddingsThe same key and wallet do things you may not have thought of yet.Done, next lesson