skip to content
Billing & caching

Gateway

Billing & caching

Pay as you go, per token, with the cost of every request in its response headers.

Metering

Gateway usage is paid from a prepaid balance rather than a monthly invoice. Four token classes are metered: input, output, cache read and cache write, at the per-model rates on the catalog. Before a request runs the gateway checks the balance can cover it. Afterwards it charges the tokens actually used. Auto-recharge tops the balance up from your saved card. See Account & billing.

The receipt

Every response carries receipt headers naming the model you asked for, the model that served, and the settled cost itemised across the four token classes, in integer nanodollars ($1 = 1e9). The full list is on Routing. On a streamed response the cost headers are absent and the cost rides the final usage event instead. To cap a single request, send x-conifer-max-cost-nanousd.

Prompt caching

On Anthropic models the gateway manages the prompt cache for you, marking the stable part of a conversation for caching once more turns are coming. If your request already carries cache_control markers they are used as sent. Send x-conifer-cache: off to skip caching on one request.

Cache reads are billed at a fraction of the input rate, and where a model prices cache writes the rate is a little above input. A rate of 0 in the catalog means that class is not charged separately. The API reference has a copy-paste cache_control request and the usage fields that report cached tokens. How the cache fits the rest of a request is on Routing.

When the money runs out

HTTP 402 billing
{
  "error": {
    "type": "insufficient_allowance",
    "code": "insufficient_quota",
    "docs_url": "https://conifer.build/console#/billing"
  }
}

This is HTTP 402 with type insufficient_allowance and code insufficient_quota. Your balance cannot cover the request, or billing is not set up yet. No model was called and nothing was charged. The status stays 402 and is never remapped to 429. The body’s docs_url points at the console. Fix it on /console.

HTTP 402 spend cap
{
  "error": {
    "type": "cost_ceiling_exceeded"
  }
}

If a request would exceed the ceiling you sent in x-conifer-max-cost-nanousd, the gateway refuses it with 402 cost_ceiling_exceeded before anything is spent. A key minted with its own spend cap returns 402 key_spend_cap_exceeded once that cap is reached, whatever the account balance.

HTTP 402 key spend cap
{
  "error": {
    "type": "key_spend_cap_exceeded",
    "key_id": "…",
    "cap_nanodollars": 5000000000,
    "spent_nanodollars": 4900000000,
    "would_charge_nanodollars": 200000000
  }
}

A key whose spend cap cannot cover the request’s worst case is refused as 402 key_spend_cap_exceeded. Distinct from account prepaid and the per-request ceiling. Nothing charged. Fields: key_id, cap_nanodollars, optional spent_nanodollars (omitted, never null, when that spend figure was unreadable), would_charge_nanodollars. No code. No docs_url. No balance_nanodollars. Clients branch on type.