429, check the error type and retry hints before sending another request.
Understand rate limits
API keys support RPM and TPM limits. These limits serve different purposes from spending quotas:View and configure limits
Open API Keys in the console and click Edit for the key. Check or update RPM Limit and TPM Limit. For key creation, spending quotas, and other key management tasks, see Manage API keys. Leaving an RPM or TPM field empty, or setting it to0, means that no custom limit is set for that field.
429. Use the actual response to identify the cause, rather than relying only on the key configuration.Identify a rate-limit response
Check the HTTP status first, followed byerror.type and, when present, error.code.
402 indicates a billing rejection, so check your balance or spending quota. For HTTP 401, 400, or 422, fix authentication or the request first. See Error handling for the full classification.
Response example
The following example shows an RPM rejection for a non-streaming Chat Completions request. The limit of1 is illustrative, not the platform’s default RPM. Request identifiers have been replaced with placeholders.
Selected response headers:
x-ratelimit-* request-limit headers shown above. Keep their original values for troubleshooting, but do not treat them as a guarantee that the next request will succeed or substitute x-ratelimit-reset-requests for an explicit retry hint.
Fields and headers vary by error. Clients must handle missing optional fields rather than requiring every protocol or every 429 response to match this example.
Inspect a single request
This curl example disables automatic retries so that you can inspect one request’s HTTP status, headers, and body. SetAPI_KEY to an existing key first. Do not put keys in source code or logs.
model with an available model ID as needed. This example is for inspecting a response, not for repeatedly sending requests to trigger a limit. A successful request can incur charges. HTTP 200 alone does not establish that generation finished normally: also check the content and the protocol’s completion status.
Wait and retry within bounds
Handle an explicit rate-limit error in this order:- Record the error. Keep the HTTP status, error type, error code, request ID, and retry hints.
- Check the retry budget. Set a maximum number of attempts, a cumulative wait limit, and a timeout for the entire operation. Count the initial request as an attempt.
- Calculate the wait.
Wait at least the number of seconds in
error.retry_after_sec, when present. Also read a parseableRetry-Afterheader. If neither provides a usable hint, apply your application’s exponential backoff and jitter instead of retrying immediately. - Wait, then try again.
Read the new response’s hints rather than reusing the previous wait value. Further
429responses remain subject to the same budget. - Stop at the limit. Let the application handle the failure, for example by asking the user to try later or pausing a batch. Contact support if failures persist.
429 loop automatically.
Retry boundaries for streaming
For a request that explicitly returns429 before any output begins, use the strategy above to decide whether to retry. Do not automatically replay a request after receiving partial output: doing so can duplicate content or incur additional charges.
For streaming calls, check in-stream errors and completion events as well as the initial HTTP status. Follow the event format for the selected protocol; the non-streaming JSON example is not a universal format for streaming errors.
Control traffic and observe changes
Backoff handles failed requests; it does not replace traffic control during normal operation.- Smooth request traffic. Queue batch work instead of sending a whole batch at once.
- Limit concurrency. Bound in-flight requests and separately control the rate at which requests start. Lower concurrency alone may not prevent RPM limiting.
- Manage token usage. Remove unnecessary repeated context and set an output budget that fits the task. Do not treat billable tokens or a response’s
usageas the remaining live TPM allowance. - Prevent retry amplification. Apply the same client-side traffic controls to initial requests and retries.
Investigate persistent rate limiting
Check the key in use, its RPM/TPM settings, request timing, and automatic retries in your client and SDK. If429 continues after the indicated waits, stop repeatedly trying and provide support with:
- Request time and time zone.
- Model ID, endpoint path, and whether the request used streaming.
- HTTP status,
error.type,error.codewhen present, and error message. - Request ID and
traceIdwhen present. - Current and previous retry hints, actual wait durations, and attempt count.
- Original
x-ratelimit-*headers when present. - The key’s RPM/TPM configuration and client traffic pattern.
Authorization header. Redact business data in request bodies, logs, and screenshots.
FAQ
Why can requests return 429 when RPM or TPM is set to 0?
Why can requests return 429 when RPM or TPM is set to 0?
0 removes the custom limit for that field, not the other limit or every service limit. For example, if TPM is 0, still check RPM. Identify the limiting factor from the actual error rather than the setting alone.Why am I still rate-limited after waiting for Retry-After?
Why am I still rate-limited after waiting for Retry-After?
Does a per-minute limit reset at the next clock minute?
Does a per-minute limit reset at the next clock minute?
60. Read the actual retry hint instead of fixing the recovery time at 60 seconds, and handle failures that persist after waiting.Why do I get 429 when average RPM is below my limit?
Why do I get 429 when average RPM is below my limit?
Can I calculate TPM directly from usage.total_tokens?
Can I calculate TPM directly from usage.total_tokens?
usage.total_tokens as a rate-limit counter or a live remaining TPM allowance. Usage describes that request’s consumption. Cache, reasoning, and other tokens follow protocol-specific counting rules; billing usage alone does not establish the TPM counting rule.Will a higher spending quota, a top-up, or more keys resolve 429?
Will a higher spending quota, a top-up, or more keys resolve 429?
402, investigate billing. For 429, investigate the actual limit and request traffic. Raising a spending quota does not raise throughput, and adding or rotating keys must not be used to bypass limits.Are 429 requests billed, and can I retry immediately if they are not?
Are 429 requests billed, and can I retry immediately if they are not?
429 are not billed; see Token usage and billing. Billing and rate-limit counting are separate questions. An unbilled rejection is not a reason to retry repeatedly without waiting. Follow retry hints and your retry budget.Related guides
- Manage API keys: Manage keys, spending quotas, and custom rate limits.
- Error handling: Find other error types and recommended actions.
- Token usage and billing: Understand token types, pricing, and charges for failed requests.
- View metrics: Observe aggregate call trends.
- View usage: Inspect individual requests’ usage and timing.

