Decide quickly: billing block or temporary rate limit?
| Status code | Documented examples in OpenAI-compatible APIs | Should you retry immediately? | Safe first action |
|---|---|---|---|
| "402" | "Used by some OpenAI-compatible providers to signal payment or credit problems (for example, an insufficient account balance or exhausted prepaid credit)." | "No. Treat it as a hard billing or credit block until the account condition is fixed." | "Stop automatic retries. Check your account’s balance, credit limits, and billing configuration, correct any issues, then retry once the provider confirms the account is in good standing." |
| "429" | "Used by OpenAI and some compatible providers for rate limiting or too many requests scenarios; some OpenAI errors also use 429 for a hard credit_balance_exhausted condition rather than a transient throttle." | "Only after you confirm it represents a temporary limit (not a credit or quota exhaustion) and respect any server-provided delay." | "Inspect the error subtype and headers (such as any delay or Retry-After indication). If it’s a transient rate limit, slow down, space out requests, and retry with backoff. If it indicates exhausted credit or quota, treat it like a billing/quota block and resolve that condition before retrying." |
When a 402 or 429 response does not clearly fit these patterns, do not assume it is simply a rate limit or a billing block. Read the error message and structured fields, check your provider’s documentation for that status and error subtype, and, if needed, contact support. Confirm whether the problem is transient throttling or a payment/credit issue before deciding whether to retry or change account settings.
What the HTTP specs actually say about 402 and 429
HTTP status code 402 is defined in the core HTTP semantics specification with the reason phrase "Payment Required" and is explicitly described as "reserved for future use".[1] The standard gives the name but does not assign detailed behavior or required handling; it leaves room for individual APIs to decide what kinds of payment or credit conditions, if any, they want to signal with 402.
HTTP status code 429 is defined in a separate RFC as "Too Many Requests" and is described as indicating that the user has sent too many requests in a given amount of time, i.e., rate limiting.[2] The specification notes that responses should include details explaining the condition and may give guidance on how and when to retry.[2]
Taken together, these definitions support a practical distinction: 402’s "Payment Required" label naturally fits use as a signal that some payment or credit prerequisite must be satisfied before calls can succeed again, whereas 429’s "Too Many Requests" definition directly targets temporary overload or rate-limit scenarios where success is possible once the client slows down or waits.[1][2] That said, the standards do not force a particular billing or retry policy; they only reserve the codes and describe their general purpose.
Because providers have flexibility within these bounds, you cannot assume that every 402 is a billing block or every 429 is a simple per-second throttle. When the behavior is unclear, inspect the error details and confirm the exact semantics in the provider’s documentation before deciding whether to change account settings or implement a retry strategy.
How OpenAI and compatible providers use 402 and 429 in practice
OpenAI’s published error reference associates HTTP 429 with at least two distinct conditions. One entry describes "429 - Rate limit reached for requests" with the cause "You are sending requests too quickly" and a solution that explicitly recommends pacing requests and following any Retry-After header, which is a textbook rate-limiting scenario.[3] In the same reference, OpenAI also documents "429 - Credit balance exhausted" with the cause "Your organization has no prepaid credits remaining" and a solution of adding credits before continuing to use the API.[3] In other words, OpenAI uses 429 both for transient throttling (where careful retries are appropriate) and for a hard credit exhaustion state (where calls will not succeed again until funds are added).
DeepSeek’s OpenAI-compatible API instead uses HTTP 402 specifically for a billing condition: "402 - Insufficient Balance" with the cause "You have run out of balance" and the solution "check your account's balance, and go to the Top up page to add funds."[4] The same DeepSeek error list assigns HTTP 429 to "Rate Limit Reached" with causes such as sending requests too quickly or exceeding concurrency or QPS limits, and advises clients to pace requests reasonably.[4] In DeepSeek’s mapping, 402 clearly indicates a payment or credit problem that will not be resolved by waiting, while 429 indicates a temporary limit that can be addressed by slowing or spacing requests.
These documented patterns lead to different handling: for OpenAI, a 429 linked to rate limiting can be treated as a temporary condition and retried with backoff and respect for any delay headers, whereas a 429 labeled as credit balance exhausted should trigger a billing or credit fix before further calls.[3] For DeepSeek, 402 Insufficient Balance similarly calls for topping up the account or adjusting billing, while 429 Rate Limit Reached again calls for pacing and retrying.[4] Use these provider-specific mappings as a guide, but always defer to the exact wording and error subtypes in each provider’s documentation to determine whether a given 402 or 429 is a retryable limit or a payment/credit block.
Safe handling strategies for 402 and 429 in your client
Treat 402 as a hard stop and 429 as a paced-retry signal, unless you have explicit evidence to the contrary.
When your client receives HTTP 402, halt automatic retries for that operation. Instead, record the failure and trigger an account or billing check. That usually means verifying current balance, any credit or spending limits, and whether billing details (such as payment methods or invoices) are in good standing. Automated logic should capture enough context for an administrator to understand what happened, but avoid looping retries while the underlying payment issue remains unresolved.
A practical pattern is to log the 402 with relevant identifiers, mark the affected tenant or organization as blocked for paid operations, and surface an alert or UI message indicating that billing needs attention. Only once the account has been corrected and you have confirmation that calls should succeed again should your system resume normal traffic, either by clearing the block flag or allowing the next user-initiated request to proceed.
For HTTP 429, assume it represents a temporary limit and respond by slowing down and retrying carefully. Do not immediately replay the same request in a tight loop. Instead, apply backoff between attempts, and respect any delay information the server provides (for example, a Retry-After or similar header). Spacing requests out and reducing concurrency helps you move back under the provider’s limits without creating more errors.
Keep 429 handling bounded: cap the number of retries and the maximum total wait time, and stop if the same request continues to hit 429 beyond those limits. At that point, treat it as an operational issue that needs configuration or usage changes rather than more automated retries. This avoids runaway retry storms that can worsen throttling, strain both your system and the provider, or violate stated usage policies.
Handling ambiguous or provider-specific uses of 402 and 429
When a provider’s behavior doesn’t clearly match the usual "402 for payment, 429 for rate limiting" pattern, pause and gather more information before deciding how your client should react.
Some services use 429 for more than simple per-second caps—for example, to indicate that you have exhausted a quota or credit allocation, even though the status text still says "Too Many Requests." Others may introduce 402 without explaining precisely which billing or entitlement condition it represents. In these cases, retrying as if it were a transient throttle or treating it as a permanent block based on assumptions can lead to brittle behavior.
Start by examining the error payload your client receives. Look at any structured fields and messages, including provider-specific error codes, human-readable descriptions, and metadata that hints at whether the issue is temporary ("slow down", "try again later") or absolute ("no balance", "quota exceeded"). Check headers such as Retry-After or custom rate-limit headers; the presence of a concrete delay and limit information is a strong signal that the provider expects paced retries rather than billing changes.
If the meaning is still unclear, go to the provider’s official documentation or support channels. Search for descriptions of their 402 and 429 responses, associated error codes, and recommended client behavior. If necessary, contact support with a sample error (redacting any sensitive data) and ask whether it represents a retryable limit or a payment/quota block.
Once you have confirmed the provider-specific semantics, update your handling logic accordingly. Keep a clear separation between retryable limits—where you slow down, honor any indicated delays, and cap retries—and hard account or billing blocks, where you stop automated retries and require an account change before attempting further calls. This alignment ensures your client behaves safely and predictably even when status codes are used in non-standard ways.