Guides

Key limits

A key’s own spending limit, the models it may use, and when it expires, with what a refusal looks like.

On this page

Spending limits

You can give a key its own spending limit, separate from the account’s balance. Open Developer, find the key, then Limits: an amount and a period. Leave the amount empty and the key spends like the account.

PeriodResets
Day00:00 UTC each day
Week00:00 UTC on Monday
Month00:00 UTC on the first of the month
TotalNever

The counter adds up what each request is charged at the prices on the Models page, cached reads and writes included. It is checked before the model runs, so a request that would take the key past its limit is refused even when the account has plenty of credit. The Developer page shows what the key has spent, what is left and when the period ends.

When a key is over its limit

Past its limit, the key’s requests are not run and answer 429 with the code api_key_budget_exceeded. The account’s balance is untouched.

Response
HTTP/1.1 429 Too Many Requests
x-request-id: req_7c1e0a5d42f94b8ea6c39d0b1f5a7e28

{
  "error": {
    "message": "This API key has reached its spending limit",
    "type": "insufficient_quota",
    "param": null,
    "code": "api_key_budget_exceeded"
  }
}

This is a different refusal from insufficient_quota, which means the whole account is out of credit and every key it owns stops. Raise the limit, or wait for the period to turn over. Retrying sooner changes nothing.

Model allow-lists

A key can also be limited to a list of models, ticked in the same Limits panel. No list means every model, which is how a key starts.

  • GET /v1/models lists only the models the key may use, so an SDK asking what is available gets the same answer the API enforces.
  • Naming a model outside the list in chat completions, Responses, Messages, count tokens, or the model’s own endpoint answers 403 with model_not_allowed.
  • Up to 100 model IDs can be ticked on one key.
Response, Anthropic format
HTTP/1.1 403 Forbidden
x-request-id: req_2d84af06be1347c1a90e5f3a76c2b8d4

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "This API key can’t use that model"
  }
}

The OpenAI format carries the same refusal as { "code": "model_not_allowed", "type": "invalid_request_error" }. The idea is one key per application: a key that leaks cannot be used on models you kept off its list.

Expiry

A key can be given a date and time to stop working, in the same panel. After that moment the API answers 401 with invalid_api_key on its next request, the same refusal as a revoked or made-up key. GET /v1/models and count tokens can still answer for it for up to a minute, as neither charges anything.

Extending the date on the Developer page brings a lapsed key back, once the date is in the future again. Revoke is the permanent one: a revoked key cannot be restored.