On this page
- 01What you'll set up
- 02How a budget works
- 03Choose how a budget is enforced
- 04Set the budget
- 05A worked example
- 06One budget for everything on the policy
- 07What callers see at the limit
- 08If the budget check cannot run
- 09Test it before you rely on it
- 10Pick starting values
- 11Keep it as code
- 12Roll out in three steps
- 13If something goes wrong
01
What you'll set up
In about eleven minutes you will give a policy a monthly and a daily budget, choose how it is enforced, prove it works with a test key, and decide what happens if the budget check itself cannot run.
- A monthly and a daily budget on a policy
- An enforcement style that fits how much control you want
- A test that shows the limit working before real traffic depends on it
- A clear, readable response when a limit is reached
- A rollout that never surprises a team
You need an owner or admin role and a policy bound to the traffic you want to cap. If you do not have a policy yet, start with the guide on creating your first policy.
02
How a budget works
A budget is checked before a request reaches the provider. If there is room, the call runs and its real cost is counted. If there is not, the call never leaves, so a blocked request adds no spend.
1Request arrives
Key, team, app
2Policy found
Most specific binding
3Budget checked
Daily and monthly room left
4Room left
The call runs and its cost is counted
5No room
HTTP 402, nothing sent to the provider
The same budget applies to requests on your own provider keys and to requests paid with Cloptima credits.
03
Choose how a budget is enforced
Every budget has an enforcement style. It decides what happens when spend reaches the limit.
| Enforcement | What it does | Use it when |
|---|---|---|
| Alert only (never blocks) | Tracks spend against the budget and never stops traffic | You are learning what normal spend looks like |
| Block at the budget | Refuses requests before they reach the provider once the budget is used | You want a firm limit. This is the console default |
04
Set the budget
Budgets live on the policy form. The monthly budget is in the Basics section. The daily budget and the enforcement style are in Limits.
- 1
Open the policy
Go to AI → Policies, open the policy you want to cap, and choose Edit. For a new app, choose Govern a new app and open Customize settings.
- 2
Set the Monthly budget
In Basics, enter the most this policy may spend in a calendar month, in US dollars. The presets are a quick start.
- 3
Set the Daily budget
Open Limits and enter the daily limit. It cannot be higher than the monthly budget.
- 4
Choose the enforcement style
Still in Limits, choose At the budget.
- 5
Save
Choose Update policy. The budget applies to new requests at once.
Basics
- 2Monthly budget
- 2000$500$2000$5000
Limits
- 3Daily budget
- 100
- 4At the budget
- Block at the budget
05
A worked example
Take a support assistant on one policy with a monthly budget of $3,000, a daily budget of $150, and Block at the budget. The numbers below are an illustration.
| Time (UTC) | What happens | Result |
|---|---|---|
| Most days | Traffic costs about $60 a day | Well inside both budgets |
| Tuesday 14:00 | A retry bug in a new release doubles the calls | Spend climbs fast |
| Tuesday 17:40 | Today's spend reaches $150 | New requests return HTTP 402 with the daily budget named |
| Tuesday 17:45 | The team sees the 402s and ships a fix | The monthly budget still has most of its room |
| Wednesday 00:00 | The daily budget resets | Traffic resumes under the same limits |
Without a limit, the same bug would have run until someone noticed the invoice. With one, the cost of the mistake is capped at the daily budget.
06
One budget for everything on the policy
A budget belongs to the policy. Every app, team, and key bound to the policy spends from the same daily and monthly budget, so one limit covers a whole group.
| Goal | How |
|---|---|
| Give each team its own budget | Create one policy per team and bind each to its team |
| Put one ceiling over all AI gateway spend | Set an org-wide budget on the org baseline policy and choose Block at the ceiling |
| Keep a company ceiling even when a team sets its own | Nothing extra. A request spends from the winning policy's budget and also counts toward the org-wide ceiling |
| Hold the same budget on edge gateways | Nothing extra. Every edge spends from a share of the same policy budget and org-wide ceiling as the cloud gateway |
A team budget under a company ceiling
The org baseline caps all AI gateway spend at $10,000 a month. The research team's own policy allows $15,000. A research request spends from the research budget and also counts toward the org ceiling. When the organization reaches $10,000, new requests stop with gateway_org_monthly_budget_exceeded, even though the research budget still has room.
07
What callers see at the limit
At the limit the request stops before it reaches the provider. The response is HTTP 402 and names the budget that was reached, so a developer knows what happened without opening a ticket.
{
"error": "Your AI request was blocked because the daily AI spend limit has been reached.",
"reason": "gateway_daily_budget_exceeded",
"violations": ["gateway_daily_budget_exceeded"],
"details": { "daily_budget_usd": "500", "estimated_cost_usd": "0.0123" }
}| Reason | Meaning |
|---|---|
| gateway_daily_budget_exceeded | The daily budget was reached. Requests resume after the UTC reset or when you raise it. |
| gateway_monthly_budget_exceeded | The monthly budget was reached. Requests resume next month or when you raise it. |
from openai import OpenAI, APIStatusError
client = OpenAI(base_url="https://api.cloptima.ai/v1/ai", api_key="clop_vk_...")
try:
reply = client.chat.completions.create(
model="gpt-5.4-mini",
messages=[{"role": "user", "content": "Summarize this ticket"}],
)
except APIStatusError as error:
body = error.response.json()
if error.status_code == 402:
# Budget reached: queue the work or tell the user, do not retry in a loop
print(body["reason"], body.get("details"))
else:
raise08
If the budget check cannot run
Budget checks run on Cloptima's own services. On the rare occasion one cannot run, who pays for the request decides what happens. There is nothing to set.
Your own provider keys
- The request continues, so a budget check that cannot run never blocks your traffic
- Your budget applies again as soon as the check runs
Cloptima credits
- The request waits for its budget decision, and stops if there is none
- No credit is spent without a budget decision
On an edge gateway that has lost contact with Cloptima, the org baseline setting "Keep serving if an edge gateway loses contact with Cloptima" decides what happens when the edge needs more of a budget. A policy can turn serving off for its own apps. Requests that run on Cloptima credits never run without a budget decision.
09
Test it before you rely on it
Prove the limit with a throwaway policy. It takes a few minutes and removes any doubt.
- 1
Create a test policy
Set a Monthly budget of a few dollars and a Daily budget of a few cents. Choose Block at the budget.
- 2
Bind it to a test key
Create a virtual key for the test and bind the policy to that key.
- 3
Send test calls
Open AI → Credentials & Keys, open Test Virtual Key, select the key, and choose Send Test Call. Repeat until the daily budget is used.
- 4
Read the 402
You should see the reason and the budget that was reached.
- 5
Clean up
Delete the test policy and key, or raise the budget to a real value.
10
Pick starting values
Start from how the app behaves today, then tighten after a week of real usage.
| Setting | A good start |
|---|---|
| Daily budget | About twice a typical day, so normal growth never trips it |
| Monthly budget | The AI budget your finance team has approved |
| Maximum output size | Set one on the policy. It keeps the cost of each request predictable |
Use AI → Explorer to find a typical day. Group by App for the last 7 days and read the spend column.
11
Keep it as code
Teams that manage infrastructure in Terraform can keep budgets in a pull request.
resource "cloptima_llm_gateway_policy" "support_production" {
name = "support-production"
mode = "enforce"
budget_mode = "hard"
allowed_providers = ["openai"]
allowed_models = ["openai/gpt-5.4-mini"]
daily_budget_usd = 150
monthly_budget_usd = 3000
}In Terraform, budget_mode accepts observe, soft, or hard. soft is Alert only and hard is Block at the budget in the console.
12
Roll out in three steps
You do not need to switch on blocking everywhere at once.
- 1
Start with Alert only
Set the budgets and watch spend in the Explorer for a week.
- 2
Block on one app
Switch to Block at the budget on a policy bound to a single app.
- 3
Widen the binding
Bind the policy to more apps and teams as confidence grows.
13
If something goes wrong
Most surprises come from the enforcement style or from which policy applies.
| What you see | Likely cause | Fix |
|---|---|---|
| 402 gateway_daily_budget_exceeded | The daily budget was reached | Wait for the UTC reset, or raise the daily budget |
| 402 gateway_monthly_budget_exceeded | The monthly budget was reached | Raise the monthly budget, or wait for the new month |
| Traffic is never stopped | Enforcement is Alert only, or the policy only monitors | Switch to Block at the budget and set the policy to Enforce |
| 402 gateway_org_daily_budget_exceeded or gateway_org_monthly_budget_exceeded | The org-wide ceiling on the baseline policy was reached | Raise the baseline budget, or wait for the reset |
| A different budget applies than you expect | Another binding won for this key, app, or team | Check the Effective policy panel on the Policies page |