Error Handling

Error Response Format

When an API request fails, it will return an error response in the following format:

{
  "error": {
    "message": "Error description",
    "type": "error_type",
    "code": "error_code"
  }
}

Common Error Codes

Authentication Error (401)

Error Code	Description	Solution
`invalid_api_key`	API token is invalid	Check if the token is correct
`expired_api_key`	API token has expired	Create a new token
`missing_api_key`	API token not provided	Add Authorization in the request header

# Correct authentication method
curl https://api.smai.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key"

Request Error (400)

Error Code	Description	Solution
`invalid_request`	Request format is incorrect	Check request parameters
`invalid_model`	Model does not exist	Use the correct model name
`context_length_exceeded`	Context exceeds limit	Reduce input content

Quota Error (429)

Error Code	Description	Solution
`rate_limit_exceeded`	Request frequency exceeded	Reduce request frequency
`insufficient_quota`	Insufficient balance	Recharge account

Insufficient Balance

When the account balance is insufficient, the API will return a 429 error. Please recharge in time to continue using the service.

Server Error (500/503)

Error Code	Description	Solution
`server_error`	Internal server error	Try again later
`service_unavailable`	Service temporarily unavailable	Try again later
`model_overloaded`	Model is overloaded	Try again later or switch to another model

Error Handling Example

from openai import OpenAI, APIError, RateLimitError, AuthenticationError

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

try:
    response = client.chat.completions.create(
        model="gpt-4.1",
        messages=[{"role": "user", "content": "Hello"}]
    )
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except RateLimitError as e:
    print(f"Request frequency exceeded: {e}")
except APIError as e:
    print(f"API error: {e}")

Retry Strategy

For transient errors (such as 429, 503), it is recommended to implement exponential backoff retries:

import time
from openai import OpenAI, RateLimitError

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

def call_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4.1",
                messages=messages
            )
        except RateLimitError:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # 1, 2, 4 seconds
                print(f"Request frequency exceeded, retrying in {wait_time} seconds...")
                time.sleep(wait_time)
            else:
                raise

Summary of HTTP Status Codes

Status Code	Description
200	Request successful
400	Request parameter error
401	Authentication failed
403	Insufficient permissions
404	Resource not found
429	Request frequency exceeded or insufficient balance
500	Internal server error
503	Service temporarily unavailable

Get Help

If you encounter an error that cannot be resolved, please contact customer service:

WeChat Customer Service: SmallAI2024
Provide error information and request ID for quick issue resolution.

Error Handling

On this page