Error Codes

When an API request fails, xmAI returns a JSON error response with an appropriate HTTP status code.

Error Response Format

All errors follow a consistent format:

{
  "error": {
    "type": "error_type",
    "message": "Human-readable description of the error",
    "code": 401
  }
}

Field	Type	Description
type	string	Machine-readable error type
message	string	Human-readable error description
code	number	HTTP status code

Error Types

HTTP Status	Type	Description
401	unauthorized	Invalid or missing API key
402	insufficient_balance	Insufficient balance — please top up
403	forbidden	No permission to access this resource
429	rate_limited	Too many requests — rate limit exceeded
503	model_unavailable / service_unavailable	Model or service is temporarily unavailable
500	internal_error	Internal server error

Error Response Examples

401 Unauthorized

{
  "error": {
    "type": "unauthorized",
    "message": "Invalid API key provided",
    "code": 401
  }
}

402 Insufficient Balance

{
  "error": {
    "type": "insufficient_balance",
    "message": "Insufficient balance, please top up",
    "code": 402
  }
}

403 Forbidden

{
  "error": {
    "type": "forbidden",
    "message": "You do not have permission to access this resource",
    "code": 403
  }
}

429 Rate Limit Exceeded

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded, please retry after 60 seconds",
    "code": 429
  }
}

503 Model Unavailable

The type field is model_unavailable when a specific model cannot be reached, or service_unavailable for general service errors.

{
  "error": {
    "type": "model_unavailable",
    "message": "Model gpt-4o is temporarily unavailable, please try again later",
    "code": 503
  }
}

500 Internal Error

{
  "error": {
    "type": "internal_error",
    "message": "An unexpected error occurred",
    "code": 500
  }
}

Handling Errors

Python

from openai import OpenAI, APIError

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

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except APIError as e:
    print(f"Error {e.status_code}: {e.message}")

Node.js

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: 'sk-your-xmai-key',
  baseURL: 'https://api.xmai.sg/v1',
})

try {
  const response = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello!' }],
  })
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.log(`Error ${error.status}: ${error.message}`)
  }
}

Best Practices

• 401: Check that your API key is correct and included in the Authorization header
• 402: Top up your balance at console.xmai.sg/wallet
• 429: Implement exponential backoff and retry logic
• 503: Retry with a different model or wait and retry
• 500: Contact support if the error persists