Routing and failover
How each call is routed to a healthy upstream and retried automatically inside the same request, what the public reliability figures mean, and how to steer a call by cost and latency with maxCredits and preferLatencyUnderMs.
Last updated
On this page
You call a SKU; we take care of everything behind it. Each call is routed to the best healthy upstream for your input, retried automatically on another route if an attempt fails, and charged only for the answer that came back. Which upstream answered is an internal detail: responses, request history and the catalog never name it. What you can always see is what you care about: whether the API is working, and what a call costs.
How a call is routed
For every call the router builds a list of eligible routes and tries them in order.
1. Filter. A route is eligible only if all of these hold:
- it is connected in our deployment,
- its circuit breaker is not open (below),
- its price in credits for your input fits
maxCredits, if you set one.
2. Order. The cheapest eligible route for this input goes first (for per-result APIs, the credits of the largest result your input allows), then by measured health. With preferLatencyUnderMs, routes that usually answer within your target go first.
3. Try in order. Each attempt has its own timeout. What happens next depends on how the attempt ended:
| Attempt outcome | What the router does |
|---|---|
| Answer (including "not found") | Stops and returns it. You pay the credits of this answer. |
| Timeout, upstream error, rate limit or block | Retries automatically on the next eligible route, inside the same request. |
| The upstream says your input is invalid | Stops with 400 invalid_input: retrying would not help. Nothing is charged. |
| The route cannot serve this kind of input (for example a country it does not cover) | Moves on silently. |
If every attempt fails, the credits held for the call come back in full and you get 502 all_sources_failed. You pay nothing; retry later with backoff (with the same Idempotency-Key):
{
"code": "all_sources_failed",
"error": "Every source failed for this request. You were not charged.",
"requestId": "req_01JBXR2V4X6Z8B0D2F4H6K8M0P"
}The requestId is all support needs to see exactly what happened on our side.
Circuit breakers
Every route has its own circuit breaker, so a failing upstream is taken out of rotation within seconds instead of slowing your calls down:
- Closed: normal. Every failure is counted; a success resets the count.
- Open: after 5 consecutive failures the router stops sending calls to that route.
- Half-open: after a 30-second cool-down one call is allowed through. If it succeeds the breaker closes; if it fails it opens again.
"This route cannot serve this input" and "your input is invalid" never count as failures, so one odd input cannot take a healthy route out of rotation. If every breaker of an API is open at once, the router does not refuse your call: it probes the route whose last failure is oldest.
Reliability you can check
Health is measured from real traffic, not claimed, and published per API. Every API's reference page, GET /v1/apis/{sku} (health), GET /v1/catalog, GET /v1/status/apis and the Network page show the same figures over the last 30 days:
| Field | Meaning |
|---|---|
status | operational, degraded, outage or unknown (below). |
successPct | Share of calls that returned an answer (found or not found). Calls rejected for the caller's own reasons (invalid input, balance, limits) are not counted. |
uptimePct | Share of 5-minute intervals with traffic in which the API answered. |
latencyP50Ms, latencyP95Ms | Response time of answered calls: median and 95th percentile. |
requests | Calls measured in the window. |
status describes the API right now:
- outage: the API cannot be served at the moment (it is not available in this deployment, or every route's breaker is open), or fewer than half of recent calls succeeded,
- degraded: fewer than 95% of recent calls succeeded (failed calls are never charged),
- operational: everything else with enough traffic,
- unknown: too little traffic to say yet (fewer than 5 measured calls in the last 24 hours and in the last 30 days).
"Recent" means the last 24 hours when there were at least 5 measured calls, otherwise the 30-day window. Until an API has traffic, its figures read null (shown as "—"), never a made-up number.
Routing controls
Add either of these fields to the JSON body of POST /v1/run/{sku} or POST /v1/quote/{sku}, next to the SKU's own input. The router removes them before the input is validated.
| Field | Type | Default | Effect |
|---|---|---|---|
maxCredits | integer | none | The most this call may cost, in whole credits. Dearer routes are skipped and the credits held for the call are capped at this amount. |
preferLatencyUnderMs | integer | none | Prefer routes that usually answer within this many milliseconds. Best effort; never refuses a call. |
maxCredits
Put a hard ceiling on one call:
{ "email": "[email protected]", "maxCredits": 2 }The call is never charged more than 2 credits, and no more than 2 credits are held for it. If the API cannot serve this input within the cap, the call fails before anything runs with 400 invalid_input, and details carries maxCredits (your cap) and cheapestCredits, the least this input can be served for. For per-result APIs the price depends on the input: lowering limit can bring a call under the cap.
maxCredits replaced the dollar cap maxCostUsd on 2026-11-09. A request that still sends maxCostUsd is refused with 400 invalid_input rather than run without the cap you meant to set; details names the replacement:
{
"code": "invalid_input",
"error": "maxCostUsd is no longer supported: calls are priced in credits. Set maxCredits (whole credits) instead.",
"requestId": "req_01JBXS6Z8B0D2F4H6K8M0P2R4T",
"details": { "field": "maxCostUsd", "replacement": "maxCredits" }
}preferLatencyUnderMs
Favour fast answers for interactive use without giving up automatic retries:
curl -sS -X POST "https://api.primaryapi.com/v1/run/email.verify" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","preferLatencyUnderMs":800}'Routes measured at or under 800 ms median go first (cheapest among them first), then the rest. The call is never refused because of this control, and you still pay only for the answer you get.
source, allowFallbacks and ignoreSources are retired. Requests that still send them keep working: the fields are accepted and ignored, and they no longer affect routing, pricing or idempotency. Use maxCredits to bound what a call may cost.
Mistakes are rejected, not guessed
| Mistake | Response |
|---|---|
maxCredits or preferLatencyUnderMs is not a positive integer | 400 invalid_input |
The API cannot serve this input within maxCredits | 400 invalid_input with maxCredits and cheapestCredits |
The request sends the retired maxCostUsd | 400 invalid_input naming maxCredits as the replacement |
| The API is not available in this deployment | 503 service_unavailable |
None of these is charged.
Routing and idempotency
Routing controls are part of a request's identity: retrying with the same Idempotency-Key but a different maxCredits or preferLatencyUnderMs answers 409 idempotency_conflict. See Idempotency.
In the MCP server
The run_api tool takes the same controls as arguments (maxCredits, preferLatencyUnderMs), and get_api returns the API's price in credits and measured health. See MCP server.