Spend controls

Cap what your workspace and each API key can spend in a month, understand the 402 responses, and raise a limit.

Three things can stop a request from spending: your prepaid balance, a monthly limit on the key, and a monthly limit on the whole workspace. The gateway checks all of them before it calls a provider. A refused request costs nothing.

Early access. The inference gateway is deployed but switched off. Safeguard switches it on per workspace, and these controls apply from then on.

How the checks work

Before each request, the gateway holds the most the request could cost (see how a request is charged). The hold must pass these checks, in this order:

Balance. Your available credit, which is the balance minus what requests in flight hold, must cover the hold. At a balance of zero or less, every request is refused.
The key's monthly limit, if the key has one. What the key has spent this month, plus what its requests in flight hold, plus this request's hold, must stay within the limit.
The workspace's monthly limit, if one is set. The same sum for the whole workspace, Workbench runs included.

The first check that fails decides the error you get. Months are UTC calendar months, so monthly spend starts again at 00:00 UTC on the 1st.

The checks use the most a request could cost, so a request can be refused while a little credit or headroom is left. A smaller max_tokens makes the hold smaller. If you leave max_tokens out, the gateway uses 4,096 output tokens, or the model's own maximum when that is lower, for both the hold and the call. Requests in flight at the same time each hold their own amount.

The 402 responses

All three refusals are HTTP 402 with the type insufficient_quota:

`code`	Message	What to do
`insufficient_credit`	Not enough credit for this request. Add credit in the Console, or lower max_tokens.	Add credit, or lower `max_tokens`.
`key_spend_limit_exceeded`	This API key's monthly spend limit would be exceeded.	Raise or clear the key's limit, use another key, or wait for next month.
`account_spend_limit_exceeded`	Your account's monthly spend limit would be exceeded.	Ask a tenant admin or super admin to raise or clear the workspace limit.

{
  "error": {
    "message": "This API key's monthly spend limit would be exceeded.",
    "type": "insufficient_quota",
    "code": "key_spend_limit_exceeded",
    "param": null
  }
}

Retrying a 402 unchanged rarely helps. It keeps failing until credit is added, a limit changes, or requests in flight finish and release what they hold.

Limit a key

Set a limit when you create a key: on API keys, select Create key and fill in Monthly spend limit (USD, optional). To change it later, select Edit on the key's row. Leave the field empty for no limit. The Console takes dollars and cents, above zero.

The This month column on API keys shows each key's spend against its limit. The bar turns red at 90%.

A change to a key's limit reaches the gateway within 30 seconds.

Your code can read the calling key's limit and spend:

curl https://api.safeguard.sh/gpt/v1/key \
  -H "Authorization: Bearer $SAFEGUARD_INFERENCE_KEY"

Field in `data`	What it is
`monthly_spend_limit_usd`	The key's monthly limit as a string, or `null` for none.
`month_spent_usd`	What this key has spent in the current UTC month.
`available_credit_usd`	Your workspace's available credit.
`month`	The current month, as `YYYY-MM`.

The response also carries the key's name, prefix, scopes and rate_limit_rpm. If the billing service cannot be reached, the spend and credit fields are left out. The workspace limit is not part of this response.

Limit the workspace

A tenant admin or super admin sets the workspace limit. Open Usage, go to Credits and limits, and under Gateway settings fill in Workspace monthly spend limit (USD), then select Save settings. In the Console's words: "Requests that would pass it are refused." Leave it empty for no limit.

The limit applies from the next request. The Spent this month card shows how much of it is used.

Raise a limit

Refusal	Who fixes it	How
`insufficient_credit`	A tenant admin or super admin, or Safeguard	Add credit. See Credits and invoices.
`key_spend_limit_exceeded`	The key's owner	On API keys, select Edit, raise or clear Monthly spend limit (USD), and select Save. It takes effect within 30 seconds.
`account_spend_limit_exceeded`	A tenant admin or super admin	Under Gateway settings, raise or clear the workspace limit and select Save settings. It takes effect at once.

In the Workbench, these errors come with a shortcut to the right place: Open limits for a limit, and Add credit for credit once card top-up is on.

Rate limits are separate

Each key also has a limit on requests per minute: 60 unless you set another number, up to 10,000. It guards against runaway clients and is approximate, so it is not a way to cap spend. A request over it gets a 429 with a Retry-After header. See Limits.