Error Codes

HTTP Status Codes

Status Code	Meaning	Recommended Action
200	Success	--
400	Bad Request	Check JSON format and ensure all required parameters are present
401	Authentication Failed	Verify that your API Key is correct and has not expired or been disabled
403	Forbidden	This key may not be authorized to access the requested model
429	Rate Limit Exceeded	Reduce request frequency, or contact support to increase your RPM quota
500	Internal Server Error	Retry the request; if the issue persists, submit a support ticket
502/503	Upstream Service Unavailable	Wait and retry; consider switching to an alternative model

Error Response Format

{
  "error": {
    "message": "Invalid API key provided: sk-nex-xxx...xxx.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Common Errors and Solutions

`invalid_api_key`

Invalid API key provided

Cause: The API Key is incorrect or has been deleted.

Solution: Go to the console to verify the key status and re-copy the full key.

`model_not_found`

Model 'xxx' not found

Cause: The model ID is misspelled, or the model is not enabled for your plan.

Solution: Check the model ID for correctness (model IDs are case-sensitive). Query the /v1/models endpoint to retrieve the full list of available models.

`rate_limit_exceeded`

Rate limit exceeded

Cause: Request frequency has exceeded the RPM (requests per minute) quota.

Solution: Reduce request frequency and increase the interval between requests. Contact support if you need a higher quota.

`context_length_exceeded`

This model's maximum context length is xxx tokens

Cause: The combined input and output token count exceeds the model's context limit.

Solution: Reduce the input length or lower the max_tokens parameter.

Retry Strategy

For 429 and 5xx errors, we recommend exponential backoff:

import time
import openai
 
def call_with_retry(client, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
        except openai.RateLimitError:
            wait = 2 ** attempt
            print(f"Rate limited, waiting {wait}s...")
            time.sleep(wait)
        except openai.APIStatusError as e:
            if e.status_code >= 500:
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")