Budgets
Spend limits at every scope: organization, project, API key, and customer
A budget caps what a slice of your traffic can spend. Gateway enforces four independent scopes, and the first one exhausted blocks the request with a 402 before any provider is called. This page is the canonical comparison; the per-surface API pages document their field shapes.
The four scopes
The headroom headers appear on successful responses as a limit approaches, so you can alert before a breach instead of after.
Soft vs hard enforcement
- Soft limits alert at thresholds (50%, 80%, and 90% by default for projects) and let requests continue. Use them for visibility without disruption.
- Hard limits block requests with
402once exceeded, until the period resets or the limit is raised. Use them for strict cost control.
Budget configuration changes can take up to an hour to take effect in enforcement. A raised limit doesn’t unblock traffic instantly, and a new hard limit doesn’t protect you instantly.
One concept, three spellings
The same enforcement modes appear with different casing per surface: the dashboard shows Soft Limit / Hard Limit, the Projects API uses soft_limit / hard_limit, and the Embedded Routing API uses SOFT / HARD. They behave identically.
Choosing a scope
Give every production workload a project budget; it’s the scope with alerting thresholds and per-period reporting. Add per-key limits for keys you hand to individuals or customers, so one credential can’t drain a project. The organization credit is the backstop above everything, and customer budgets apply only if you resell Gateway through the Embedded Routing Stack.