Per-key budgets, and why every team eventually wants them

Every team we onboard arrives with one API key in one environment variable, shared by production, the batch pipeline, and whatever an intern is prototyping. It works right up until it doesn't.

Failure looks the same every time

• A retry loop with no ceiling runs from Friday evening to Monday morning.
• A staging job points at production credentials and quietly doubles the bill.
• Nobody can answer 'which service spent this?' because there is only one key.

What we shipped

Keys now carry an optional hard budget and an independent rate limit. When a key hits its budget the gateway returns 402 for that key only; everything else keeps serving. Budgets reset on your billing cycle or on a schedule you set.

POST /v1/keys
{
  "name": "batch-pipeline",
  "budget_usd": 500,
  "budget_period": "monthly",
  "rpm": 600
}

It is a small feature. It has prevented more unpleasant invoices than anything else we have built.