API limits: balance, key caps, size and context

What can stop a request, the code you get in each case, and what to do. Every limit has its own code, so your program can tell them apart.

Subscriptions#

Subscriptions run in the supported apps and have two usage limits only: a 5-hour limit and a weekly limit. When you reach one, requests answer 429 with USAGE_LIMIT_EXCEEDED until the limit renews on its schedule; quick retries don't help. Your dashboard shows how much of each limit you have used and when it renews; details in Usage limits.

Pay-as-you-go keys#

The subscription limits don't apply here. What limits your requests:

• Balance: when it runs out, requests answer 403 with INSUFFICIENT_BALANCE. Top up, then try again.
• The key's spend limit, if you set one: 429 with API_KEY_QUOTA_EXHAUSTED, or insufficient_quota on /v1/responses. Raise the limit in the key settings.
• The key's expiry date and IP allow-list, if you set them: API_KEY_EXPIRED and ACCESS_DENIED.

Request rate#

Too many requests in a short time answer 429 with RATE_LIMITED. Repeated requests with a wrong key are slowed down too, with INVALID_AUTH_RATE_LIMITED. Wait, then retry with a delay that doubles each time.

Request size#

A request that is too large answers 413 with REQUEST_TOO_LARGE. It usually comes from many or large images or files. Make images smaller, send fewer at once, or put long documents in a file and send only the parts you need. Endpoints that carry only text, such as Embeddings, accept smaller bodies than the chat endpoints.

Context length#

When the conversation is longer than the model's context window, the request answers 400 with CONTEXT_LIMIT_EXCEEDED. Start a new conversation, remove older messages, or summarize them. The context window of each model:

Error shapes#

Errors come in two shapes, depending on where they happen.

From the key, balance and limit checks, before any model is called:

{ "code": "INVALID_API_KEY", "message": "Invalid API key" }

While serving the request, in the format of the endpoint you called, with a request_id; the same id is in the X-Request-ID header. On the OpenAI-compatible endpoints:

{
  "error": {
    "type": "invalid_request_error",
    "code": "CONTEXT_LIMIT_EXCEEDED",
    "message": "This conversation exceeds the model context limit. Start a new conversation or remove older content."
  }
}

On /v1/messages the same fields sit in error, with "type": "error" at the top level; on Gemini the error has a numeric code, a message and a status. Send the request_id when you contact us about a failed request.

Codes while serving the request#

• INVALID_REQUEST · 400: the model could not process the request as sent. Check the fields and values.
• CONTEXT_LIMIT_EXCEEDED · 400: the conversation is longer than the model's context window. Shorten it.
• REQUEST_TOO_LARGE · 413: the request body is too large. Send smaller or fewer images and files.
• RATE_LIMITED · 429: the model is busy for the moment. Wait a little, then retry.
• MODEL_UNAVAILABLE · 503: the model is temporarily unavailable. Retry, or pick another model.
• SERVICE_UNAVAILABLE · 503: a temporary problem on our side. Retry after a moment.
• AUTHENTICATION_FAILED · 503: a temporary problem on our side, not your key. Retry after a moment.
• UPSTREAM_TIMEOUT · 504: the model took too long to answer. Retry; for long tasks use streaming.
• INTERNAL_ERROR · 500: an unexpected error. Retry; if it repeats, contact us with the request_id.

The codes from the key, balance and limit checks are in Errors and fixes.

When to retry#

• 429, 500, 503 and 504 are temporary: retry with a delay that doubles each time, and cap the number of attempts.
• 400, 401, 403 and 413 won't go away on retry: fix the request, the key or the balance first.
• USAGE_LIMIT_EXCEEDED clears when the limit renews, not with retries.