Skip to navigation
Projects and cost

Budgets

Spend limits at every scope: organization, project, API key, and customer

Gateway checks four independent budget scopes. The first one exhausted returns 402 before any vendor call, so a blocked request costs nothing.

The four scopes

ScopeConfigured inPeriodsOn breach (402 code)Response headers
Organization creditBilling settingsBalance-basedbudget_exceeded, or payment_failed when a payment failsX-Credit-Balance-USD, X-Budget-Limit-USD, X-Budget-Warning
Project budgetThe project’s Configuration tab, or the Projects APIDaily, weekly, monthly, quarterly, yearlyproject_budget_exceededX-Project-Budget-Remaining-USD, X-Project-Budget-Limit-USD, X-Project-Budget-Warning
Per-key spend limitSpend limit (optional) when creating a key, or limit and limit_reset in the Management APIDaily, weekly, monthlyapi_key_limit_exceededX-Key-Limit-Remaining-USD, X-Key-Limit-USD, X-Key-Limit-Warning
Customer budgetThe Embedded Routing customer budget, one per customerDAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLYnull (error type is budget_exceeded)None. Read spend from the customer usage API

Remaining and limit headers appear while a budget exists; *-Warning appears past a warning level (project alert thresholds, or 80 and 90 for per-key limits) and carries that percentage. Enterprise organizations get only X-Credit-Balance-USD, which goes negative between invoices. Customer-scoped keys get no organization or project headers.

How limits are enforced

  • Periods are calendar-aligned in UTC, not rolling: weekly from Monday, monthly from the 1st, quarterly from January, April, July, and October 1, yearly from January 1
  • Spend is recorded after each request, so the request that crosses a limit completes and blocking starts with the next
  • Project budgets apply only to requests scoped by a project API key or the X-Project-Id header, never to one naming its project only in the project_id body field

Budget changes take up to an hour to enforce, whether raising a limit or adding a hard one.

Soft vs hard limits

A soft limit alerts and never blocks. A hard limit alerts, then returns 402 until the period resets or you raise it. The Projects API spells them soft_limit and hard_limit; the Embedded Routing API, SOFT and HARD.

Project budget alerts

Thresholds are budget percentages: the dashboard pre-fills 50%, 80%, and 90%, and an API-created budget has none unless sent. An alert sends on the project’s first request after a crossing.

Alerts go to the budget’s recipients (any address, no Merge account needed) plus every admin while Also notify organization admins is on (the default). With it off and no recipients, one admin is emailed.

Each threshold emails when first crossed, with at most one reminder seven days later; a higher threshold emails right away, and a hard limit emails when it starts blocking. The throttle resets each calendar month regardless of budget period.

Choosing a scope

Give every production workload a project budget, the scope with alert emails, and add per-key limits to keys you hand out so one credential can’t drain a project. Organization credit is the backstop; customer budgets apply only if you resell Gateway through the Embedded Routing Stack.

Next steps

Projects

Create a project and scope requests so its budget applies

Budgets API

Manage project budgets from infrastructure-as-code

Cost governance and savings

See where spend is reported and the settings that cut it