Budgets & spend limits
Which spend control to reach for, and how they interact.
Kontinent gives you three ways to cap spending, plus the prepaid balance underneath them. They are not alternatives. They stack, and each answers a different question.
| Control | What it pools over | Typically set by | Can warn first |
|---|---|---|---|
| Key spend limit | One API key | The engineer | No |
| Team budget | Every key assigned to a team | Finance | Yes |
| Guardrail budget | Every key bound to a guardrail | Platform owner | No |
| Credit balance | The whole organization | Whoever tops up | Yes |
Which one to reach for
Give every key a limit. This is the blast-radius control. One key usually means one service or one script, so a limit here answers "what is the worst a runaway loop or a leaked credential can cost me?" It is the cheapest protection available and the one most likely to actually save you money.
Use a team budget for accountability. When the question is organizational, such as Engineering gets €2,000 a month, a team budget pools spend across every key assigned to that team. Unlike a per-key limit, it keeps holding when someone adds another key. It is also the only one of the three spend controls that can warn you before it blocks. The credit balance warns too, but it is the floor underneath, not a budgeting tool.
Use a guardrail budget when your grouping is not the org chart. A guardrail groups keys by purpose or policy rather than by team, for example everything doing customer-facing inference, no matter who owns it. If your grouping is the org chart, prefer a team budget: it is clearer and it can warn.
They stack, and the strictest wins
Every applicable limit is checked independently, so a request is refused as soon as any one of them is exhausted. There is no precedence to learn: a key can sit under its own limit, a guardrail budget and a team budget at once, and whichever runs out first is the one that stops it.
A key that belongs to no team is not covered by any team budget. Dissolving a team never deletes or disables its keys. They keep working, they simply stop being counted against that budget. Give such keys their own limit.
What you see when a limit is hit
Both a spend limit and a rate limit return 429, so check the code field.
| Code | What ran out | What to do |
|---|---|---|
spend_limit_exceeded | A key, guardrail or team budget | Read the message. It names which one. |
rate_limit_exceeded | The key's requests per minute | Back off and retry. |
insufficient_credits | The organization's prepaid balance | Top up. Retrying before that will keep failing. |
The message on spend_limit_exceeded tells you which limit stopped the request, because the three sit in different places in the console.
Two things that surprise people
A limit with no reset period is a lifetime cap, not a monthly one. When you create a key, the reset selector defaults to never. A €100 limit with that default is €100 for the life of the key. It does not refill next month. Choose daily, weekly or monthly if you want it to roll over.
A guardrail budget replaces your organization's default, it does not combine with it. Attaching a guardrail that carries its own budget means that budget applies instead of the default one. So a generous guardrail budget loosens the key rather than tightening it. This is deliberate: it is what lets you give one key more room without raising the limit for everybody.
Budgets and credits behave differently on purpose
Budgets fail open. If our counters are briefly unreachable, requests are allowed rather than refused. A limit you set on yourself should never turn our infrastructure problem into your outage.
The credit balance fails closed. Once credit is exhausted the answer is a hard 402 until a top-up lands.
This is why the balance is a poor budgeting tool: hitting zero stops everything for everyone at once. Treat it as an outage to be avoided with auto top-up, and do your budgeting in the three controls above.