Second choice API providers should be treated as an ordered outage plan, not as names in a procurement spreadsheet. The useful second choice is a provider that already passed the current request constraints and can be promoted without rebuilding discovery while the primary route is failing.
That does not require paying two providers for every result. It requires keeping the decision, adapter, credentials, and promotion rule ready. The distinction matters. Duplicate execution is expensive and can create duplicate side effects. An untested fallback is cheap until the exact moment it is needed, when missing input mappings and expired credentials turn it back into a vendor search.
A runner-up is different from a rejected candidate
A provider can lose a ranking in two ways. It can fail a hard requirement, or it can pass every requirement and rank below the winner. Only the second case creates a runner-up.
`GET /v1/decide?candidates={id},{id}` preserves that distinction. It returns the selected provider, the rule that selected it, rejected candidates with the exact constraint that removed each one, and eligible runners-up in order. A candidate excluded by `max_price`, `max_latency_ms`, `min_reliability`, `settlement`, or required inputs is not an outage route. Promoting it would discard a requirement precisely when operators have the least time to inspect the consequences.
The ordered runner-up is more useful. It answered the same request and survived the same gates. Its lower rank may come from the chosen `optimize_for` weighting rather than a broken contract. This is why overruling an automated provider choice can be a small recorded action when the alternative already appears in the decision response.
Eligibility still has a scope. The runner-up passed the requirements and measurements available for that comparison. It did not receive a permanent approval for every workload or future date.
Keep the route warm without buying every result twice
A hot standby receives work continuously and can take over immediately. A cold fallback is discovered and integrated after failure. Most API buyers need something between those extremes: a warm route whose contract is exercised and whose decision is current, but which does not duplicate every paid request.
Keep these parts warm:
- the stable `candidate_id` and the ordered decision response that named the runner-up;
- valid credentials or a currently allowed settlement path;
- a tested mapping from the workflow's canonical inputs to the provider's required fields;
- response validation for the fields the next workflow step consumes;
- a timeout and retry budget that leaves time for one alternate attempt;
- an idempotency or deduplication rule for calls that may produce side effects;
- an owner and a timestamp for the last representative fallback test.
These checks cost less than shadowing all production traffic. Some can run without making a paid provider call at all. Schema fixtures can exercise the adapter. A credential check can detect an expired key. A fresh comparison can confirm that the candidate still satisfies price, latency, reliability, settlement, and input requirements. When a representative call is necessary, its cadence and cost belong in your own readiness policy.
Do not confuse a health endpoint with proof that the route works. It may answer while the paid operation rejects the real input, returns a changed shape, or cannot complete settlement. The test must cross the same boundary the production workflow will cross.
Define promotion as a rule, not an operator hunch
“Try the backup when the primary looks bad” leaves the hardest decision until the incident. State which failures permit another attempt and which ones stop the workflow.
A timeout before response headers, a configured retryable server error, or a rate-limit response may justify moving to the next eligible provider. Invalid authentication usually requires fixing credentials. Invalid input usually follows the request to every provider unless the adapters differ. A partial stream, accepted asynchronous job, or uncertain payment can make a second attempt unsafe because the first call may still finish.
The promotion rule therefore needs both a trigger and a boundary. The trigger describes the observed failure. The boundary proves that the workflow can safely construct a new attempt. Switching API providers mid-workflow is only safe where portable state, provider-owned state, and settlement responsibility are separated.
Circuit breakers and cooldowns can enforce the trigger, but they do not choose a contract-compatible replacement. They stop repeated calls to an unhealthy route. The stored decision supplies the next eligible route. Keep those responsibilities separate so a health mechanism cannot promote a candidate that failed the buyer's requirements.
Refresh the ranking before it becomes incident evidence
The runner-up order can change without either provider going offline. Prices can change. The buyer may supply a different input set. Measured latency or success rate may become available. The permitted settlement path or optimization target may change.
Refresh the decision when those inputs change and on a cadence appropriate to the workflow. The score is 0–100 relative to the candidates in that one comparison. It is returned with the weights and each candidate's contribution per dimension. A score copied into a runbook without its candidate set and weights is not a durable ranking.
Unmeasured dimensions are dropped from the weighting and named, never scored zero. Result quality and provider terms are not measured by Apiosk. Your fallback test must cover the output contract your workflow needs, and your own review must cover provider terms. The minimum API comparison fields explain what the machine-readable record can establish and where buyer verification still starts.
External x402 discoveries cannot fill the runner-up slot. They appear in a separate `external_candidates` block with no `candidate_id`. They are unreviewed, unmeasured, and not settleable through Apiosk, so they cannot chain into comparison or decision. Treat them as leads for later integration, not emergency routes.
Record both the planned and actual route
An outage plan is easier to improve when the intended fallback and the executed choice are both visible. Store the original decision, the failure that triggered promotion, the runner-up that received the request, and the outcome of that attempt.
`POST /v1/decisions` is free and unauthenticated. It records which provider was chosen and the alternatives that were rejected. That creates a stable point for later review without pretending Apiosk observed the rest of your incident. Your application should still retain request identifiers, adapter version, retry count, timing, settlement result, and any ambiguous side effect.
After recovery, review whether the runner-up remained eligible, whether the promotion rule fired at the right boundary, and whether the latency budget left enough room for a second attempt. If an operator repeatedly bypassed the first choice for the same reason, add that reason to the requirements instead of preserving it as tribal knowledge.
Where Apiosk fits
Apiosk turns a provider ranking into a reusable fallback record. `GET /v1/discover?q=…` returns reviewed candidates with stable IDs. `GET /v1/compare?candidates={id},{id}` places price, measured latency, measured success rate, input compatibility, and settlement side by side. `GET /v1/decide?candidates={id},{id}` returns the winner, the rule, exact rejections, and ordered runners-up. The same flow is available over MCP as `apiosk_discover`, `apiosk_compare`, and `apiosk_decide`.
Apiosk does not run your circuit breaker, transfer provider-owned state, measure result quality, or approve provider terms. It gives the buyer an explicit eligible second choice before the outage. The agent integration path shows how to call the chain, while your workflow decides when a safe boundary has been reached and records whether the fallback actually ran.
Frequently asked questions
Does a second-choice provider need live production traffic to stay ready?
No. Readiness can be checked through contract tests, credential checks, current comparison data, and periodic representative calls when your own policy permits them. The important point is to verify the path before an incident, not to buy every production result twice.
Is every runner-up safe to use during an outage?
A runner-up has passed the hard requirements used in that decision, but your workflow must still be able to map inputs, validate outputs, and settle the replacement call. Apiosk does not measure result quality or provider terms, so those checks remain with the buyer.
What should trigger promotion of the second-choice provider?
Use named failure classes such as a retryable timeout, a configured error response, or a measured condition outside the request requirement. Do not promote on authentication, malformed input, or an ambiguous in-flight side effect unless the workflow has a specific recovery rule.
When should the fallback decision be refreshed?
Refresh when requirements, available inputs, payment constraints, or the candidate set changes, and before relying on an old decision during an incident. A runner-up is eligible under the comparison that produced it, not permanently certified for every future request.