Cost cap

How fallback.maxCostUsd bounds a route's hold, what over_cost_cap and route_capped mean, and the single-provider caveat to know before you rely on it.

fallback.maxCostUsd is the one lever that caps what a fallback route can ever hold or charge.

What it bounds

Without maxCostUsd, a route’s hold is the sum of the first maxAttempts candidates’ prices. maxCostUsd caps that hold instead, and lowers it further when your balance is short: the route holds the largest affordable prefix of candidates, never below the requested endpoint’s own price.

{
  "endpointId": "job:company.enrich",
  "input": { "domain": "example.com" },
  "idempotencyKey": "<new unique key>",
  "fallback": { "maxAttempts": 2, "maxCostUsd": 0.05 }
}

A candidate priced above what is left of the cap is skipped with route.skipped[].code over_cost_cap, and the walk goes on to a cheaper one.

When every provider is over it

If every remaining candidate is over the cap, the run fails as route_capped before any hold, charges nothing, and error.retryHint reads “Raise fallback.maxCostUsd, or change the input; route.skipped says why each provider was skipped.” When the endpoint you asked for is already priced above maxCostUsd, the run is refused up front, naming both numbers: “fallback.maxCostUsd ($X) is below this endpoint’s price ($Y) and fallback cannot run here; raise maxCostUsd or pick a cheaper endpoint.”

The single-provider caveat

maxCostUsd bounds the hold, not necessarily the final charge. A route that ends up able to run only one provider (maxAttempts: 1, only one candidate can actually run, or every other candidate was excluded) settles like a direct run: a provider that bills more than its listed price, for example a volume-priced or provider-reported overage, can be charged up to three times the hold. See Settlement ceiling for the exact rule. A route with more than one provider never charges above its hold.

Worked example

job:web.scrape.markdown on https://example.com with {"maxAttempts": 3, "maxCostUsd": 0.02}: a provider priced at $0.03 is skipped over_cost_cap, the walk tries the two cheaper providers left, and if both are also over the remaining cap after the first attempt, the run fails route_capped with nothing charged.