rate

API 429 error: rate limit, quota, or relay upstream?

HTTP 429 can mean request throttling, account or project limits, or a relay upstream pool issue. Check error.code, response headers, and the failure scope before retrying.

429rate_limitrate_limit_exceededtoo many requests

Likely cause

HTTP 429 can mean request throttling, account or project limits, or a relay upstream pool issue. Check error.code, response headers, and the failure scope before retrying.

Recommended fixes

Capture a redacted response body, error.code, and Retry-After first
Do not blindly retry quota errors; back off and reduce concurrency for rate limits
Compare another model or endpoint with the same key to separate account issues from relay routing issues

429 / TRIAGE

A 429 is a decision point, not a single diagnosis

Do not start with repeated retries. First capture the redacted response body, error.code, Retry-After, request ID, affected model, and whether another model works with the same key.

Locate the failing layer

Request pressure

The same key succeeds at low concurrency but fails during bursts. Look for rate_limit_exceeded, Retry-After, or rate-limit headers.

Reduce concurrency and honor Retry-After

Account or project

Signals such as insufficient_quota or billing_hard_limit_reached point to credits, spend caps, or project-level limits.

Check billing and limits; do not retry blindly

Relay upstream pool

Only one model or route fails, several users fail together, or the relay reports no available upstream account. This requires relay-side confirmation.

Test another model, then contact the relay

Read the response before retrying

Observed signalLikely meaningNext action

error.code = rate_limit_exceededRequest or token rate limitHonor Retry-After, lower concurrency, add bounded backoff

error.code = insufficient_quotaCredits, budget, or project quotaCheck billing or project limits; retries will not restore quota

One model fails; another worksModel route or relay upstream channelList available models and compare the affected route

Every model and key failsRelay gateway or shared upstream incidentRun connection diagnosis and check relay status

Minimal OpenAI-compatible request

Use placeholders and keep your real key local. Add -i so the response headers are visible; remove conversation history and optional parameters while diagnosing.

BASE_URL="https://your-api.example/v1"
API_KEY="your-local-key"

curl -i "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role":"user","content":"Reply OK"}],
    "max_tokens": 8,
    "stream": false
  }'

Save these fields, not secrets

HTTP status and response time
error.type, error.code, and redacted message
Retry-After and request ID headers
Model ID, endpoint path, and UTC timestamp

Should you retry?

Yes, with a limit

A rate-limit signal includes Retry-After, or a low-concurrency request succeeds. Wait as instructed and retry no more than a small bounded number while diagnosing.

The response says insufficient_quota, billing, invalid key, or permission denied. Fix the account or access condition first.

Compare first

The payload is relay-specific or vague. Test one other model with the same key and run connection diagnosis before assigning the cause.

Official references

OpenAI API error codes DeepSeek API error codes