> For the complete documentation index, see [llms.txt](https://docs.kontinent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kontinent.ai/best-practices/budgets.md).

# Budgets & spend limits

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 — *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 — everything doing customer-facing inference, say, 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.

{% hint style="info" %}
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.
{% endhint %}

## 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.

## Related

{% content-ref url="/pages/lu40tWXSSYv1E99p9B1Z" %}
[Rate limits & credits](/features/rate-limits.md)
{% endcontent-ref %}

{% content-ref url="/pages/e4XLAToYQziKWGuYMiZu" %}
[Handling errors](/features/errors.md)
{% endcontent-ref %}

{% content-ref url="/pages/xSj7bSm8tTXfLVK8VCiE" %}
[Configuring the smart router](/best-practices/cost-quality-tuning.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kontinent.ai/best-practices/budgets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.