When an offer fails, SocialRouter retries the next one implementing the same service. The retry is transparent: you get the response from whichever offer succeeded, and you are charged only for that attempt. served_by names the offer that answered, and fallback_from appears only when the chain rolled over. Failover is on by default. It is active precisely when you don’t send a provider.

​
When failover kicks in

SocialRouter moves to the next offer when the current one:
  • returns an HTTP error (4xx or 5xx)
  • returns an explicit rate-limit response (HTTP 429)
  • stalls past its per-offer deadline (120 seconds)
  • throws any other adapter-level error
Failover does not kick in when:
  • an offer was pinned with provider, which is what pinning means
  • the request hits the global request deadline (see latency and performance)
  • the client aborts the request
  • validation fails (unknown service, input that matches no accepted shape, invalid option), because nothing was attempted and there is nothing to fail over

​
How the chain is built

Every offer implementing the service, ordered by price per record ascending (with an optional explicit rank), then filtered by capacity: an offer whose max_inputs is smaller than your batch drops out of the chain rather than blocking the call.
No provider, so the chain runs in full for reddit/subreddit.posts.
You are billed once per request, against whichever offer succeeded. Failed attempts earlier in the chain are logged but never charged.

​
Single-offer services

Some services are currently served by a single offer, so they have no fallback yet. The catalogue makes this visible: offers[] has one entry. When a second offer implements the service, failover activates automatically, with no change on your side.

​
Opting out: pin an offer

There is no fallback flag. Pinning is the opt-out:
The router attempts that offer only and surfaces its error directly. Same behaviour in the SDK (run(service, { provider })), the CLI (--provider), and the MCP server (provider).

​
Best practices

1

Leave provider out by default

Failover is the product’s edge. Pinning is for benchmarking, compliance, or fast deterministic errors, not a default.
2

Set credit limits on automated keys

Per-key credit limits cap your spend if an offer starts failing and the chain rolls through every fallback. Configure them from the dashboard.
3

Pin when latency matters more than reliability

Failover roughly doubles request time when the head fails. On latency-sensitive paths, pin the fastest offer.
4

Monitor rollovers

The usage endpoint breaks usage down by offer. A sudden shift toward the second offer in a chain usually signals an upstream problem with the first.