Errors and retries

When a request fails, start with the HTTP status code and error.message in the response.

{
  "error": {
    "message": "Model not found",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Common status codes

Status	Common cause	What to do
400	Invalid JSON, a missing field, or an unsupported parameter	Change the request according to the error message.
401	Missing or invalid API key	Copy the key again and check the request header.
402	Insufficient balance	Add credit or use a key with balance.
403	The key is disabled or has a model restriction	Check the key’s status and restrictions.
404	Incorrect API address or model name	Check the URL and copy the model name from the Pricing page again.
408	The request timed out	Retry once after waiting.
413	The upload is too large	Reduce the file or request size.
429	Too many requests	Wait a few seconds before retrying.
5xx	A temporary Omrouter or model service problem	Wait and retry a small number of times.

When to retry

408, 429, and 5xx errors are usually safe to retry. Wait about one second before the first retry, increase the wait after each failure, and limit the total number of attempts.

Do not retry automatically when:

• The API key, model name, or request parameters are wrong.
• Part of a streaming response has already been shown.
• An image, video, or other billable task has already been created.

Troubleshooting order

1. Check that the API address points to Omrouter.
2. Copy the API key again and check for extra spaces.
3. Copy the model name again from the Pricing page.
4. Remove optional features such as tools and streaming, then send the smallest possible request.
5. Find the request at the same time in Usage logs.

If an API key appears in logs, a screenshot, Git history, or an agent conversation, delete it on the Keys page and create a new key immediately.