---
title: Cost cap
description: 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.

```json
{
  "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`](/errors/job-refusals#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](/money/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.

<Related />