The provider your agent depends on goes down

A backup engine is easy to write. A backup engine that returns the same thing as the first one is the actual work.

The problem

The engine your agent calls stops answering, or starts answering in four seconds instead of one, or ships a change and returns a field with a different name. Your agent has one provider and no plan B, so the work stops. That is the visible failure, and it is the good one: somebody notices within the hour.

The bad failure is the fix. Somebody wires in a second provider and normalises whatever comes back so the code keeps running. The second engine does not return per-page text, or does not separate speakers, or names things differently. The call succeeds, the shape is right, the answer is thinner, and the bill is the same.

Nobody sees that one. There is no error, no alert and no retry. The only symptom is that the answers got worse on the days the first provider was having a bad time, and by the time anyone correlates it the logs are gone.

Why it fails locally

Writing a fallback is an afternoon. Writing a fallback that guarantees the same thing is the real job, and it is not a code problem, it is a contract problem: you have to decide what a call promises before you can tell whether the backup kept the promise.

Without that decision, every provider difference becomes a silent downgrade. One engine gives you text page by page, the other gives you one block, so page ranges work on Tuesday and not on Wednesday. One separates speakers, the other returns nothing when it is not asked to, so asking for a time range works with the primary and returns empty with the backup. Two engines label speakers two different ways, and code that matched on the label breaks on nothing.

The other half is knowing when to give up on a provider and when to keep going. An unreadable file will be unreadable on the second engine too, and retrying it just burns another call. A provider timing out is exactly the case you should retry. Sorting one from the other means classifying every error code from every provider, and the list is never finished.

The code

Nothing changes in the call. What changes is the response: engine names what actually ran and used_fallback says whether it was the backup. The price is the same either way.

read(key="<key>", mode="exact")
  -> handle, engine, used_fallback, cost_eur, structure

# when the first engine answered
  engine: "<primary>", used_fallback: false

# when it did not: same mode, same cost_eur
  engine: "<backup>",  used_fallback: true

result(handle="<handle>", pages="12-14")
  -> the same call works either way: the mode
     guarantees per-page text, so an engine that
     cannot produce it never runs this job

What it costs

The fallback is not a tier and not a surcharge. read in exact mode costs 0.016 EUR per page and listen in exact mode costs 0.008 EUR per minute whoever ends up doing the work. Which engine answered is our problem, and the full list is on pricing.

A failed attempt is not billed. If the first engine fails and the backup succeeds, you pay once, at the mode price. If every engine in the chain fails, you pay nothing: the credit that was held for the job is released.

Checking what a job will cost is free, like every call that is not work: upload, result, cancel, account. Call account(estimate_for="read") for the price per unit by mode before you commit to a large file.

What this does not do

used_fallback tells you the backup answered. It does not mean the result is worse: the contract was checked before you got it, and the check is on the fields, not on the prose.
The contract is a floor, not a ceiling. Capabilities only some engines have stay outside it and show up in the response labelled by structure_source, so you can tell a section list the engine reported from one inferred from the text.
No uptime or availability figure is promised here, because none has been measured over a meaningful period. What is guaranteed is the shape of what you get back and the price you pay for it.
If a mode has no engine that can serve it, the call fails immediately and costs nothing. It does not quietly fall back to a mode that promises less.

Without markup

This page in markdown: /problems/what-happens-when-a-provider-is-down.md. All 20 of them in one file: /llms-full.txt.