Guide

Error Codes

When an API request fails, the response includes an HTTP status code and a JSON error body with details about what went wrong. This page documents all possible error codes and how to handle them.

Error Response Format

All errors follow a consistent JSON format:

JSON

{
  "error": {
    "message": "A human-readable description of the error.",
    "type": "error_type",
    "param": "the_parameter_that_caused_the_error",
    "code": "machine_readable_error_code"
  }
}

Field	Description
message	Human-readable error description
type	Error category for programmatic handling
param	The parameter that caused the error (null if not applicable)
code	Machine-readable error code for specific error identification

Status Codes Overview

Status	Name	Description	Retryable
400	Bad Request	The request was malformed or missing required parameters.	No
401	Unauthorized	Authentication failed. Your API key is missing, invalid, or expired.	No
402	Payment Required	Your account balance is insufficient to process the request.	No
403	Forbidden	Your API key does not have permission to access the requested resource.	No
429	Too Many Requests	You have exceeded the rate limit for your API key (requests per minute or tokens per minute).	Yes
500	Internal Server Error	An unexpected error occurred on the server.	Yes
503	Service Unavailable	The service is temporarily unavailable, usually because the upstream model provider is down or overloaded.	Yes

Detailed Error Reference

Recommended Retry Strategy

For retryable errors (429, 500, 503), implement exponential backoff with jitter:

Python

import time
import random
from openai import OpenAI, RateLimitError, APIError

client = OpenAI(
    base_url="https://xylove.net/v1",
    api_key="sk-your-api-key"
)

def make_request_with_retry(max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o",
                messages=[{"role": "user", "content": "Hello!"}]
            )
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            # Exponential backoff with jitter
            wait = min(2 ** attempt + random.random(), 60)
            print(f"Rate limited. Retrying in {wait:.1f}s...")
            time.sleep(wait)
        except APIError as e:
            if e.status_code and e.status_code >= 500:
                if attempt == max_retries - 1:
                    raise
                wait = min(2 ** attempt + random.random(), 60)
                print(f"Server error. Retrying in {wait:.1f}s...")
                time.sleep(wait)
            else:
                raise

Error Codes

Error Response Format

Status Codes Overview

Detailed Error Reference

Recommended Retry Strategy

Related Documentation