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.
| Period | Resets |
|---|---|
| Day | 00:00 UTC each day |
| Week | 00:00 UTC on Monday |
| Month | 00:00 UTC on the first of the month |
| Total | Never |
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.
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/modelslists 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
403withmodel_not_allowed. - Up to 100 model IDs can be ticked on one key.
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.