LiteLLM budgets: set limits and verify request blocking

LiteLLM budget not working? Configure max_budget on the virtual key your app actually uses, then run a bounded test that proves requests are rejected for budget reasons — not just displayed in the admin UI.

Jump to the verification example (local network_mock stack, no paid provider by default) or the troubleshooting table.

Hub: Tokenminning with LiteLLM.

This page answers litellm max_budget, litellm budget exceeded, and litellm budget not working in one place.

Budgets vs rate limits vs alerts

A failed request alone does not prove budget enforcement. Match the error shape and correlate with /key/info spend.

Where should I configure the budget?

For most applications, put the cap on the virtual key the service uses for inference — not the proxy master_key.

Team scope details: LiteLLM proxy users .

Requirements (documented): budgets need Postgres. Without a database, virtual keys cannot resolve and no key/team/user budget is enforced. Global max_budget fails open without a DB. See LiteLLM budget docs .

Redis: budget reservation and cross-pod spend counters use Redis in multi-worker deployments. See budget reservation . A single local container can run with Redis for realistic concurrency behavior.

How do I create a budgeted virtual key and inspect its spend?

1. Deploy the proxy with Postgres — see proxy setup.
2. Generate a dedicated test key (keep the master key admin-only):

curl -X POST 'http://localhost:4000/key/generate' \
  -H 'Authorization: Bearer sk-<master-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "max_budget": 0.01,
    "budget_duration": "30d",
    "models": ["gpt-4o-mini"],
    "key_alias": "app-dev",
    "metadata": {"env": "dev"}
  }'

3. Inspect spend and limits before and after test traffic:

curl 'http://localhost:4000/key/info?key=sk-<virtual-key>' \
  -H 'Authorization: Bearer sk-<master-key>'

On successful completions, check x-litellm-response-cost in response headers and aggregate reports:

curl 'http://localhost:4000/global/spend/report?start_date=2026-01-01&end_date=2026-01-31&group_by=team' \
  -H 'Authorization: Bearer sk-<master-key>'

Tag requests for cost attribution

Pass tags in the request body for feature-level slicing (does not replace key budgets):

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
    user="jane_smith",
    extra_body={"metadata": {"tags": ["feature:code-review", "env:prod"]}},
)

Warning: Clients can set user freely. For backend services, issue per-user virtual keys with user_id at creation — do not rely on self-declared user for enforcement.

How do I verify that LiteLLM rejects a request because of the budget?

Central question: how do I prove this budget is enforced, rather than merely displayed?

Evidence that counts

Example rejection shapes from virtual key budgets :

{
  "detail": "Authentication Error, ExceededTokenBudget: Current spend for token: 7.2e-05; Max Budget for Token: 2e-07"
}

{
  "error": {
    "message": "ExceededBudget: Key over budget. Spend=0.01, Budget=0.001",
    "type": "budget_exceeded",
    "code": "400"
  }
}

Minimal manual proof (one allowed, one blocked)

Do not burn a large production budget to test blocking. Either:

• Use a tiny test key on a disposable proxy, or
• Lower max_budget below recorded spend with /key/update to simulate exhaustion without extra provider traffic.

# After at least one successful request recorded spend:
curl -X POST 'http://localhost:4000/key/update' \
  -H 'Authorization: Bearer sk-<master-key>' \
  -H 'Content-Type: application/json' \
  -d '{"key": "sk-<virtual-key>", "max_budget": 0.000001}'
 
curl -X POST 'http://localhost:4000/chat/completions' \
  -H 'Authorization: Bearer sk-<virtual-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "test"}],
    "max_tokens": 16,
    "stream": false
  }'

That proves the already-exhausted path. Use the verification script for concurrent near-limit behavior.

What changes when requests run concurrently?

LiteLLM 1.100.0 enables budget reservation by default. See budget reservation :

1. Estimate max cost from the request body (max_tokens) and model pricing.
2. Reserve that amount against the budget before calling the provider.
3. Reject early if the reservation would exceed the cap.
4. Replace the reservation with actual cost after the response is priced.

Near the limit, some concurrent workers succeed and others return budget_exceeded — order is not guaranteed. A single concurrency test does not prove zero overspend under all load patterns.

general_settings.disable_budget_reservation: true removes pre-request holds; concurrent requests can exceed the cap until spend is recorded (config ). LiteLLM logs a warning while this is enabled.

Why might requests be blocked before reported spend reaches the limit?

Why might requests continue when I expected them to stop?

How do I restore access after a legitimate budget reset or adjustment?

Normal recovery — raise the cap or wait for the reset window, not disable enforcement:

# Temporary increase (documented on virtual keys)
curl -X POST 'http://localhost:4000/key/update' \
  -H 'Authorization: Bearer sk-<master-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "sk-<virtual-key>",
    "max_budget": 5.0,
    "temp_budget_increase": 2.0,
    "temp_budget_expiry": "7d"
  }'

Check budget_reset_at in /key/info when budget_duration is set. Scheduled resets run on an internal scheduler (default check interval ~10 minutes; tunable via proxy_budget_rescheduler_min_time / max_time — reset docs ).

Admin spend reset endpoints exist for correcting accounting errors; prefer budget adjustment for routine recovery. After a reset, verify with one allowed request and /key/info.

Troubleshooting: budget not working

Enforcement limits (LiteLLM 1.100.0)

Documented behavior (sources ):

• Budget checks read spend from the database; Redis holds the hot cross-pod counter.
• Reservation is on by default for chat completions with token pricing.
• fail_closed_budget_enforcement (off by default) rejects with 503 when spend cannot be verified in Redis or DB.
• Batch jobs (POST /batches) cannot be fully reserved at submission — monitor completed batch cost separately.
• Streaming, images, audio, unpriced models — not covered by the walkthrough below; verify separately before trusting caps.

Observed in the local verification example (network_mock, pinned image): virtual-key max_budget blocks chat completions with structured budget_exceeded / ExceededTokenBudget errors; concurrent near-limit admission matches reservation semantics above.

Not proven by mocks: network_mock exercises proxy accounting, not your provider’s invoice. Re-run against your real model before production sign-off.

Run the budget verification example

The repo ships a bounded, opt-in script with a disposable Docker Compose stack. Default mode uses network_mock — no paid provider calls.

Files: public/examples/litellm-budget-verify/ in the wiki repo .

cd public/examples/litellm-budget-verify
docker compose up -d
 
export LITELLM_RUN_LIVE=1
# optional: LITELLM_BASE_URL=http://localhost:4000
# optional: LITELLM_MASTER_KEY=sk-litellm-budget-verify-master
node verify.mjs
 
docker compose down -v   # cleanup

Download: verify.mjs  · helpers.mjs  · docker-compose.yml  · config.yaml 

Safety caps (enforced in script)

Preflight prints a conservative cost estimate from token pricing assumptions. The script refuses to run without LITELLM_RUN_LIVE=1. CI and pnpm check never call LiteLLM or paid APIs.

What the four cases exercise

Offline unit tests in lib/litellm-budget-verify.test.ts cover error classification and cost parsing only — they do not prove live proxy enforcement.

Wiring your own provider (optional)

To test against a real model, copy the example to an isolated proxy, set provider credentials via environment variables, remove network_mock, and keep the same safety caps. Expect provider charges; the stock example does not enable this path.

Spending guardrails (production)

• Never share the master key with application code
• Set max_budget on every virtual key; use models allowlist on CI keys
• Set explicit max_tokens so reservations match real usage
• Export weekly spend via /global/spend/report
• Sync model pricing when provider rates change — cost tracking 

Related

• LiteLLM hub
• Proxy setup — Postgres, client baseURL, master key
• Model routing — fallbacks and allowlists
• Budgets, rate limits (official) 
• Proxy config settings 
• Spend tracking