OpenAI-compatible API · 429 troubleshooting

Fix HTTP 429 on an OpenAI-compatible API

A 429 response means the server applied a limit, but it does not tell you which limit until you read the error body. Separate request or token pacing from credit and spend limits, then retry without multiplying traffic.

What should you check first?

Read the JSON error code and message before changing concurrency. A 429 is a status family, not one diagnosis. OpenAI's current error guide uses 429 for request rate limits, exhausted prepaid credit, and organization spend limits.

Evidence	What it tells you	Next action
`Retry-After`	The server supplied a minimum delay for this response	Wait at least that long
Error code says rate limit	Request or token pace exceeded a limit	Reduce concurrency or throughput; add bounded backoff
Error code says credit exhausted	Retrying cannot restore credit	Check balance or billing
Error code says spend limit	An enforced account limit stopped the request	Review the account limit
No 429, only 401	The request failed authentication first	Fix the key before investigating limits

Capture one complete, redacted failure

curl -sS -D /tmp/headers.txt -o /tmp/body.json \
  https://monkeytheme.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID_FROM_YOUR_LIST","messages":[{"role":"user","content":"Reply with OK"}],"max_completion_tokens":16}'

sed -n '1,20p' /tmp/headers.txt
python3 -m json.tool /tmp/body.json

Keep the HTTP status, Retry-After, request ID, timestamp, endpoint and redacted error body. Never paste the Bearer token into a ticket or screenshot.

This review did not use a customer key or generate a traffic burst. An unauthenticated request reaches MonkeyAI's authentication layer and returns 401, not a synthetic 429. Use your own real failure evidence to identify the limiting layer.

Retry without creating a request storm

# Python SDK: make retry ownership explicit while diagnosing
import os
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://monkeytheme.com/v1",
    max_retries=2,
)

# Node.js SDK
const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://monkeytheme.com/v1",
  maxRetries: 2,
});

The official Python and Node.js SDKs currently retry eligible 429 responses twice by default. If a queue, worker, HTTP library and SDK all retry, one user action can create many upstream attempts. Choose one retry owner, set a cap, honor Retry-After, and add jitter when the header is absent.

Use this decision path

Confirm the hostname and endpoint. This guide uses https://monkeytheme.com/v1.
Call /v1/models with the same key and copy an exact Model ID.
Capture the 429 headers and JSON body without exposing the key.
Separate request/token pacing from credit and spend-limit errors.
Count SDK, proxy, queue and application retries together.
Reduce parallelism before increasing retry counts.
If the error persists, send support the timestamp, request ID, model, endpoint and redacted error code.

What this page does not claim

A successful model-list request does not prove generation capacity. A 429 does not automatically mean the model provider is down, and a missing Retry-After header does not make immediate retries safe. Limit names and scopes vary across gateways and upstream providers, so the response body is more useful than guesswork.

Sources and related guides

OpenAI API error codes: current 429 categories and retry guidance.
RFC 6585 §4: HTTP 429 and optional Retry-After semantics.
openai-python retries and openai-node retries.
API key and model troubleshooting
API 504 timeout troubleshooting

FAQ

What does HTTP 429 mean?

HTTP 429 means the server decided that the requester sent too many requests within a period. The response may include Retry-After, but RFC 6585 does not require that header.

Should I retry every 429 immediately?

No. Honor Retry-After when present. Otherwise use bounded exponential backoff with jitter. Stop after a defined number of attempts and surface the final error.

Can a 429 mean the account has no credit?

Yes. OpenAI documents 429 responses for request rate limits, exhausted prepaid credit, and organization spend limits. Read the response error code and message before changing concurrency.

Do the official OpenAI SDKs retry 429 automatically?

Yes. The current Python and Node.js README files say eligible 429 responses are retried twice by default with short exponential backoff. Application retries can multiply those attempts.

Does a successful /v1/models request rule out 429 errors?

No. A model-list request can succeed while a later generation request reaches a request, token, concurrency, credit, or upstream limit.

Was an authenticated 429 forced on MonkeyAI for this guide?

No. The production authentication route was checked, but no customer key or deliberate traffic burst was used. The diagnostic steps are based on standards, official SDK behavior, and redacted production log evidence.