Reliability: fallback models and safe retries
Models sometimes don't answer. Your app shouldn't go down with them.
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.
{
"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:
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.
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
- Give every critical model a fallback.
- Retry on 429 and 503 with a growing delay, and honour
retry-after. - Send
Idempotency-Keyon requests that must not run twice. - Watch for the
DeprecationandX-IranRouter-Successorheaders on older models.
Try a chain0 of 2 steps
- Send a request with a
modelslist and see the answer. - Open that request's row in the logs and read its chain.
What you learned
modelsgives fallbacks, and only the model that answered costs anything.Idempotency-Keymakes retries safe.- Long jobs go to the async route.
Keep your place
Sign in to the panel and each lesson and your path are saved, so you continue from the same spot on any device.