Skip to main content
Upstream providers have outages, rate limits and the occasional broken response. How AgentKey handles that depends on which surface you call.

​
Scenario Methods: automatic

Every Scenario Method is backed by one or more providers in a curated order. When the first provider fails in a way that is its fault — a transport error, a 5xx, a rate limit, an error hidden inside a 200, a body that is no longer the expected shape — the server refunds that attempt and tries the next eligible provider. At most two attempts are made, inside the method’s time budget.
What makes this safe to rely on:
  • The price does not move. You pay the method’s fixed price whichever provider ends up serving the call.
  • The shape does not move. Both providers are mapped to the same output schema; fields one provider structurally lacks are listed in unsupported_fields.
  • Nothing is hidden. The response names the provider that answered and lists every attempt in attempts[].
  • It only switches on provider faults. A bad parameter, a missing object or an empty result is returned as such and never costs you a second call.
You can also steer it: pin a provider, change the order, or turn fallbacks off with the routing parameter. See Routing & Pricing.

​
Catalog tools: you choose the tool

execute_tool runs exactly the Provider/operation you name and returns that provider’s payload. There is no automatic switch to another provider — a different tool would return a different payload, which a caller that chose a specific tool would not expect. When a catalog call fails upstream, the retry is yours to make, and usually cheap: most capabilities exist on more than one provider.
  1. Sibling surface — many providers expose the same operation under an app path and a web path (…/app/… vs …/web/…); try the other one.
  2. Sibling version — endpoints carrying v1 / v2 / v3 in the name are parallel versions of the same operation.
  3. Another provider — find_tools lists every provider for a capability; describe_tool the equivalent tool and call it.
Each retry is a separate billed call, so cap it at two or three attempts.

Check upstream health first

The free agentkey_account tool reports every provider’s health and latency, and GET /v2/ops/{method} shows live health per provider for one method.