Error Handling

Learn how to properly handle API errors to build robust applications.

HTTP Status Codes

All API endpoints use standard HTTP status codes to indicate request results.

Status	Meaning	Common Causes	Solutions
200	Success	Request processed successfully	-
201	Created	Resource created successfully	-
400	Bad Request	Invalid parameters, missing required fields, invalid values	Check request parameters and required fields
401	Unauthorized	Invalid, missing, or expired API key	Check Authorization header API key
403	Forbidden	Insufficient quota, insufficient permissions, restricted model access	Check account quota, permissions, and model availability
404	Not Found	Endpoint doesn’t exist, model not found, invalid task ID	Verify request URL, model name, and resource ID
429	Too Many Requests	Rate limit exceeded	Implement exponential backoff retry, reduce request frequency
500	Internal Server Error	Temporary server failure	Retry later, contact support if persists
502	Bad Gateway	Upstream service temporarily unavailable	Retry later
503	Service Unavailable	Service maintenance or overload	Retry later

Error Response Format

All error responses follow a consistent JSON format:


{
  "code": "error_code",
  "message": "Human-readable error description",
  "data": null
}

Field Descriptions

Field	Type	Description
`code`	string	Machine-readable error code for programmatic handling
`message`	string	Human-readable error description, can be displayed to users
`data`	any	Additional error information (usually null)

Common Error Types

1. Insufficient Quota (403)

Error Response:


{
  "code": "quota_not_enough",
  "message": "user quota is not enough",
  "data": null
}

Causes:

Insufficient account balance
Free credits exhausted
Plan limit exceeded

Solutions:

Check balance in Dashboard
Top up account or upgrade plan
Check for unpaid invoices

2. Invalid API Key (401)

Error Response:


{
  "code": "invalid_api_key",
  "message": "Invalid API key provided",
  "data": null
}

Causes:

Incorrect API key format
API key deleted or disabled
Incorrect Authorization header format

Solutions:


# ✅ Correct format
Authorization: Bearer sk-1234567890abcdef
 
# ❌ Wrong formats
Authorization: sk-1234567890abcdef  # Missing "Bearer" prefix
Authorization: Bearer sk-1234567890abcdef   # Extra space after key

3. Model Not Found (404)

Error Response:


{
  "code": "model_not_found",
  "message": "model 'invalid-model-name' not found",
  "data": null
}

Causes:

Model name typo
Model deprecated or no longer supported
Your account doesn’t have access to the model

Solutions:

Check Available Models for correct model names
Use /v1/models endpoint to get current available models


curl https://aiapi.services/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

4. Invalid Request Parameters (400)

Error Response Example:


{
  "code": "invalid_request_error",
  "message": "Invalid parameter: max_tokens must be a positive integer",
  "data": null
}

Common Parameter Errors:

Error	Cause	Fix
`max_tokens must be positive`	max_tokens ≤ 0	Use positive integer (e.g., 100, 1000)
`temperature out of range`	temperature not in [0, 2]	Set between 0.0 ~ 2.0
`invalid message format`	messages format incorrect	Check if array, each item has role and content
`model is required`	Missing model parameter	Add model field

Example Fix:


// ❌ Wrong
{
  "model": "gemini-2.5-flash",
  "messages": "Hello"  // Should be array
}
 
// ✅ Correct
{
  "model": "gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

5. Rate Limit (429)

Error Response:


{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "data": {
    "retry_after": 60
  }
}

Response Headers:


X-RateLimit-Limit-Requests: 60
X-RateLimit-Remaining-Requests: 0
X-RateLimit-Reset-Requests: 1640995200

Retry-After: 60

Solutions: See Rate Limits documentation for details and best practices.

6. Task Not Found (404)

Error Response:


{
  "code": "task_not_found",
  "message": "Task with id 'abc123' not found",
  "data": null
}

Causes:

Task ID doesn’t exist
Task expired and cleaned up
Invalid task ID format

Solutions:

Verify task ID is correct
Ensure task was created successfully and correct task_id was obtained
Async tasks typically have 7-day validity period

7. Content Filtered (400)

Error Response:


{
  "code": "content_filtered",
  "message": "Your request was rejected due to content policy",
  "data": {
    "reason": "inappropriate_content"
  }
}

Causes:

Input content violates usage policy
Generated content triggered safety filters

Solutions:

Modify input to avoid sensitive or inappropriate content
Review Terms of Service for restrictions

Error Handling Best Practices

1. Implement Retry Logic

Python


import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
 
def create_session_with_retries():
    """Create session with automatic retries"""
    session = requests.Session()
 
    retry_strategy = Retry(
        total=3,                    # Max 3 retries
        backoff_factor=1,           # Exponential backoff: 1s, 2s, 4s
        status_forcelist=[429, 500, 502, 503, 504],
        allowed_methods=["POST", "GET"]
    )
 
    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("https://", adapter)
    session.mount("http://", adapter)
 
    return session
 
# Usage example
session = create_session_with_retries()
response = session.post(
    'https://aiapi.services/v1/chat/completions',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'model': 'gemini-2.5-flash', 'messages': [...]}
)

JavaScript


async function callWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
 
      // Success or non-retryable error
      if (response.ok || ![429, 500, 502, 503].includes(response.status)) {
        return response;
      }
 
      // Rate limit: use Retry-After
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
        console.log(`Rate limited. Retrying in ${retryAfter}s...`);
        await sleep(retryAfter * 1000);
        continue;
      }
 
      // Other retryable errors: exponential backoff
      const delay = Math.pow(2, i) * 1000;
      console.log(`Error ${response.status}. Retrying in ${delay/1000}s...`);
      await sleep(delay);
 
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
 
  throw new Error('Max retries exceeded');
}
 
function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
 
// Usage example
const response = await callWithRetry(
  'https://aiapi.services/v1/chat/completions',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gemini-2.5-flash',
      messages: [...]
    })
  }
);

Go


package main
 
import (
  "time"
  "math"
  "net/http"
)
 
func CallWithRetry(url string, req *http.Request, maxRetries int) (*http.Response, error) {
  client := &http.Client{}
 
  for i := 0; i < maxRetries; i++ {
    resp, err := client.Do(req)
 
    // Network error
    if err != nil {
      if i == maxRetries-1 {
        return nil, err
      }
      time.Sleep(time.Duration(math.Pow(2, float64(i))) * time.Second)
      continue
    }
 
    // Success or non-retryable error
    if resp.StatusCode < 500 && resp.StatusCode != 429 {
      return resp, nil
    }
 
    // Rate limit
    if resp.StatusCode == 429 {
      retryAfter := resp.Header.Get("Retry-After")
      // Parse Retry-After and wait...
      time.Sleep(time.Duration(math.Pow(2, float64(i))) * time.Second)
      continue
    }
 
    // Server error: exponential backoff
    time.Sleep(time.Duration(math.Pow(2, float64(i))) * time.Second)
  }
 
  return nil, fmt.Errorf("max retries exceeded")
}

2. Graceful Error Handling


def call_api_safely(prompt):
    """Safely call API and handle all errors"""
    try:
        response = requests.post(
            'https://aiapi.services/v1/chat/completions',
            headers={'Authorization': f'Bearer {API_KEY}'},
            json={
                'model': 'gemini-2.5-flash',
                'messages': [{'role': 'user', 'content': prompt}]
            },
            timeout=30  # Set timeout
        )
 
        # Check HTTP status
        response.raise_for_status()
 
        # Parse response
        data = response.json()
        return data['choices'][0]['message']['content']
 
    except requests.exceptions.Timeout:
        print("❌ Request timeout, please retry later")
        return None
 
    except requests.exceptions.HTTPError as e:
        # Parse error response
        try:
            error_data = e.response.json()
            error_code = error_data.get('code', 'unknown')
            error_message = error_data.get('message', str(e))
        except:
            error_code = 'unknown'
            error_message = str(e)
 
        # Handle by error type
        if e.response.status_code == 401:
            print(f"❌ Invalid API key: {error_message}")
        elif e.response.status_code == 403:
            print(f"❌ Insufficient quota: {error_message}")
        elif e.response.status_code == 429:
            print(f"❌ Rate limit exceeded: {error_message}")
        elif e.response.status_code == 404:
            print(f"❌ Resource not found: {error_message}")
        else:
            print(f"❌ API error [{error_code}]: {error_message}")
 
        return None
 
    except requests.exceptions.ConnectionError:
        print("❌ Network connection failed, check network")
        return None
 
    except Exception as e:
        print(f"❌ Unknown error: {str(e)}")
        return None

3. Monitoring and Logging


import logging
from datetime import datetime
 
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
 
def call_api_with_logging(prompt):
    """API call with logging"""
    start_time = datetime.now()
 
    try:
        response = requests.post(
            'https://aiapi.services/v1/chat/completions',
            headers={'Authorization': f'Bearer {API_KEY}'},
            json={
                'model': 'gemini-2.5-flash',
                'messages': [{'role': 'user', 'content': prompt}]
            }
        )
 
        duration = (datetime.now() - start_time).total_seconds()
 
        # Log successful request
        logger.info({
            'event': 'api_call_success',
            'model': 'gemini-2.5-flash',
            'duration_seconds': duration,
            'status_code': response.status_code,
            'tokens_used': response.json().get('usage', {}).get('total_tokens', 0)
        })
 
        return response.json()
 
    except Exception as e:
        duration = (datetime.now() - start_time).total_seconds()
 
        # Log failed request
        logger.error({
            'event': 'api_call_failure',
            'error': str(e),
            'duration_seconds': duration,
            'prompt_length': len(prompt)
        })
 
        raise

Error Troubleshooting Checklist

When encountering errors, check the following items:

API key correct: Check key format, prefix, and validity
Endpoint URL correct: Verify correct base URL and path
Request format correct: Validate JSON format, required parameters, and parameter types
Model name correct: Check Available Models for correct model name
Sufficient quota: Check account balance and available quota
Rate limit: Confirm not exceeding rate limits
Network connection: Ensure network is accessible, no firewall blocking
Timeout setting: Set reasonable timeout (recommend 30-60 seconds)

Getting Help

If issues persist after following this guide:

Check FAQ
Check API Status Page
Contact Technical Support

💡 Tip: When contacting support, please provide complete error response, request example (sanitized), and timestamp to help us resolve your issue faster.