API error codes and troubleshooting

Start with the HTTP status and response body. Keep the request ID and timestamp before changing the request.

Status	Meaning	What to check
400	Invalid request or unsupported field and model combination	Request body, required fields, model capability, and context limit
401	Missing, invalid, or disabled key	Host, authorization header, and environment variable
403	The key cannot use the requested model	Key model permission and exact model ID
429	Balance, quota, or rate limit	Balance, key limits, and retry-after
500–504, 529	Temporary service or model-provider failure	Retry only safe requests with capped exponential backoff

Before retrying

• Fix 400, 401, and 403 instead of repeating the same request.
• Follow retry-after when it is present.
• Set a retry limit and add jitter for temporary failures.
• Do not automatically repeat an operation that can create duplicate work or charges.

Contact support

Include the timestamp and time zone, endpoint, status, model, request ID, streaming mode, client name, and client version. Send a redacted error response. Do not include the complete API key or private prompt content.

See Support for the evidence checklist.