Cap your AI spend

This guide puts a dollar limit on your AI spend that the gateway enforces before your provider is called. At the end you will have an armed cap, you will have seen what it answers when it is reached, and you will know how to raise it.

Before you start

• Your traffic goes through the gateway: your SDK's base URL is https://api.recovea.ai/v1 or https://api.recovea.ai, and it sends a Recovea key (Quickstart). A cap bounds only the traffic that goes through the gateway.
• To cap the whole organization you need to be an Owner or an Admin. To cap one key, a Member will do (Roles).

1. Open the Limits page

In the platform, platform.recovea.ai, go to Settings → Organization → Limits. Every cap on the organization and on its keys is on this page.

2. Set the cap

Choose what to bound:

• The whole organization: under Organization caps, Set a cap on this organization.
• One key: under Caps on keys, Add a cap, and pick the key. The same control is on the key's own row in Settings → Organization → API keys, as Cap, and on the reveal step when you mint a key.

The form has four fields:

1. The amount and the window. Type the amount and choose the window: per day, week, month or year, or for the lifetime of the cap. Windows reset at 00:00 UTC (Caps and windows).
2. Enforce a hard stop. Turn it on to arm the cap. Off, the cap counts and sends its alerts and refuses nothing, which is a way to watch the number for a week before you enforce it.
3. Spend alerts. Three rows are there already, at 50, 80 and 95 percent, each with its dollar figure. Keep them, change them, or Add an alert: any whole percentage from 1 to 100, up to ten.
4. Alert recipients. The addresses the alerts go to.

Save. A yearly cap asks you to confirm before its hard stop goes on, because a year is the longest a mistaken stop can last.

3. Check that it is armed

The organization's cap is a card on the Limits page; a key's cap is a line in Caps on keys. The switch beside it reads Armed, and the card shows what is used, what is left, and when the window resets, in UTC and in your own clock.

4. Send a request and read the headers

curl -sS -D - https://api.recovea.ai/v1/chat/completions \
  -H "Authorization: Bearer $RECOVEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"ping"}]}'

A request served under an armed cap carries the cap's kind and window:

x-recovea-budget-scope: organization
x-recovea-budget-window: month

On a key's cap the scope is key. If neither header is on the response, no armed cap stood over the request: check the switch in step 3, and check that the request used the key you capped.

5. Know what the refusal looks like

When the window's spend reaches the cap, the next request is refused before your provider is called, so the refused request costs nothing:

HTTP/1.1 402 Payment Required

{
  "error": {
    "message": "Monthly budget reached. Traffic resumes at reset, or raise the cap.",
    "type": "insufficient_quota",
    "param": null,
    "code": "budget_exceeded"
  }
}

The message names the window; a cap on one key adds "for this API key". Branch your code on the status, error.type and error.code, never on the message. Do not retry a 402: every retry is refused the same way until the window resets or the cap is raised.

A 503 with error.code budget_unverifiable and Retry-After: 1 is different: the cap could not confirm its spend for a moment. Retry it (Fail-open and fail-closed).

A cap stops the next request, not the ones already running, so the window's total can end a little above the cap. Cap explains by how much.

6. Hear about it before it happens

Each alert fires once per window, when spend reaches its percentage, and emails every recipient on the cap. It fires on a cap whose hard stop is off, too, and a 100% alert is a warning that the cap was reached, not a refusal. When the window resets, every alert re-arms.

Threshold alerts are Team and above; a refusal mails your owners and billing contacts on any plan, Free included, once per budget each month. On Team and above, the Alerts page lists the alerts that fired (Alert thresholds).

7. Raise the cap

On the cap's card or line, Edit, change the amount, and save. What the window has already spent is kept, because the count belongs to the scope and the window, not to the cap's amount. The new amount reaches the gateway on the control plane's next push, which runs every five seconds, and requests are served again as soon as the count is under the new cap.

To stop refusing without changing the amount, turn Enforce a hard stop off. The cap goes on counting and alerting.

What you have now

An armed cap that refuses at its line with a 402 your code can branch on, alerts on the way up, and a Limits page that shows what is used and what is left. Where a cap is set has every control on that page and who may use it.