When the provider chosen for your request returns an error or rate-limits you, SocialRouter retries with the next compatible provider in the chain. The retry is transparent — you receive the response from whichever provider succeeded, and you are only charged for that successful attempt. The response’s provider field tells you which provider served the result, and fallback_from is populated when the originally-requested provider was bypassed.

​
When failover kicks in

SocialRouter falls back to the next provider when the current one:
  • Returns an HTTP error (4xx or 5xx)
  • Returns an explicit rate-limit response (HTTP 429)
  • Throws any other adapter-level error
Failover does not kick in when:
  • The request hits the deployment-level execution cap (see latency and performance)
  • The request is aborted by the client
  • Validation fails (invalid URL, unsupported platform or type)

​
Single-provider extractions

Some (platform, type) combinations are currently served by a single provider, so failover does not apply to them yet. The provider listing on /providers marks these with a “failover soon” badge. When a second provider is integrated for that combination, failover activates automatically — no change required on your side.

​
How the chain is built

For a given (platform, type) pair, SocialRouter assembles the chain from every active provider that supports it, sorted by per-record cost ascending. The cheapest compatible provider is tried first. If you pin a provider slug, that provider is moved to the head of the chain — the remaining compatible providers stay as fallbacks behind it. 
{
  "url": "https://linkedin.com/in/example",
  "provider": "apify/linkedin/profile.info"
}
You are billed once per request, against whichever provider succeeded. Failed attempts on earlier providers are logged but never charged.

​
Disabling fallback per request

If you want a fast, deterministic error rather than a slower fallback success — for example to detect that a specific actor is broken — send fallback: false: 
{
  "url": "https://linkedin.com/in/example",
  "provider": "apify/linkedin/profile.info",
  "fallback": false
}
The router collapses the chain to the requested provider only and surfaces its error directly. Available on both /v1/extract and /v1/search. The same flag exists on the SDK (extract({ fallback: false }), search({ fallback: false })), the CLI (--no-fallback), and the MCP server.

​
Best practices

1

Set credit limits on automated keys

Per-key credit limits cap your spend if a provider starts failing and the chain rolls through every fallback. Configure them from the dashboard.
2

Pin a provider when latency matters more than reliability

Failover roughly doubles request time when the primary fails. For latency-sensitive paths, pin the fastest provider directly.
3

Monitor failover via the usage endpoint

The usage endpoint exposes which provider served each request. A sudden rise in fallback usage often signals an upstream provider issue.