错误处理

了解如何正确处理API错误，构建健壮的应用程序。

HTTP状态码

所有API端点使用标准HTTP状态码表示请求结果。

状态码	含义	常见原因	解决方案
200	成功	请求成功处理	-
201	已创建	资源创建成功	-
400	请求错误	参数格式错误、必需参数缺失、参数值无效	检查请求参数格式和必需字段
401	未授权	API密钥无效、缺失或已过期	检查Authorization头中的API密钥
403	禁止访问	配额不足、权限不足、模型访问受限	检查账户配额、权限和模型可用性
404	资源不存在	端点不存在、模型不存在、任务ID无效	验证请求URL、模型名称和资源ID
429	请求过于频繁	超过速率限制	实现指数退避重试，降低请求频率
500	服务器内部错误	服务器临时故障	稍后重试，持续失败请联系支持
502	网关错误	上游服务暂时不可用	稍后重试
503	服务不可用	服务维护或过载	稍后重试

错误响应格式

所有错误响应都遵循统一的JSON格式:


{
  "code": "error_code",
  "message": "人类可读的错误描述",
  "data": null
}

字段说明

字段	类型	说明
`code`	string	机器可读的错误代码，用于程序化处理
`message`	string	人类可读的错误描述，可直接显示给用户
`data`	any	附加错误信息(通常为null)

常见错误类型

1. 配额不足 (403)

错误响应:


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

原因:

账户余额不足
免费额度已用完
超出套餐限制

解决方案:

登录控制台查看余额
充值账户或升级套餐
检查是否有未支付的账单

2. 无效的API密钥 (401)

错误响应:


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

原因:

API密钥格式错误
API密钥已被删除或禁用
Authorization头格式不正确

解决方案:


# ✅ 正确格式
Authorization: Bearer sk-1234567890abcdef
 
# ❌ 错误格式
Authorization: sk-1234567890abcdef  # 缺少 "Bearer" 前缀
Authorization: Bearer sk-1234567890abcdef   # 密钥后有空格

3. 模型不存在 (404)

错误响应:


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

原因:

模型名称拼写错误
模型已下线或不再支持
您的账户无权访问该模型

解决方案:

查看可用模型列表获取正确的模型名称
使用 /v1/models 端点获取当前可用模型


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

4. 请求参数错误 (400)

错误响应示例:


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

常见参数错误:

错误	原因	修复
`max_tokens must be positive`	max_tokens ≤ 0	使用正整数 (如: 100, 1000)
`temperature out of range`	temperature不在[0, 2]范围	设置为 0.0 ~ 2.0 之间
`invalid message format`	messages格式不正确	检查是否为数组，每项包含role和content
`model is required`	缺少model参数	添加model字段

示例修复:


// ❌ 错误
{
  "model": "gemini-2.5-flash",
  "messages": "Hello"  // 应该是数组
}
 
// ✅ 正确
{
  "model": "gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

5. 速率限制 (429)

错误响应:


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

响应头:


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

Retry-After: 60

解决方案: 参见速率限制文档了解详情和最佳实践。

6. 任务未找到 (404)

错误响应:


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

原因:

任务ID不存在
任务已过期被清理
任务ID格式错误

解决方案:

检查任务ID是否正确
确认任务创建成功并获取了正确的task_id
异步任务通常有7天有效期

7. 内容过滤 (400)

错误响应:


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

原因:

输入内容违反使用政策
生成内容触发安全过滤器

解决方案:

修改输入内容，避免敏感或不当内容
查看使用政策了解限制

错误处理最佳实践

1. 实现重试逻辑

Python


import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
 
def create_session_with_retries():
    """创建带自动重试的session"""
    session = requests.Session()
 
    retry_strategy = Retry(
        total=3,                    # 最多重试3次
        backoff_factor=1,           # 指数退避: 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
 
# 使用示例
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);
 
      // 成功或不可重试的错误
      if (response.ok || ![429, 500, 502, 503].includes(response.status)) {
        return response;
      }
 
      // 速率限制: 使用 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;
      }
 
      // 其他可重试错误: 指数退避
      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));
}
 
// 使用示例
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)
 
    // 成功或网络错误
    if err != nil {
      if i == maxRetries-1 {
        return nil, err
      }
      time.Sleep(time.Duration(math.Pow(2, float64(i))) * time.Second)
      continue
    }
 
    // 成功或不可重试的错误
    if resp.StatusCode < 500 && resp.StatusCode != 429 {
      return resp, nil
    }
 
    // 速率限制
    if resp.StatusCode == 429 {
      retryAfter := resp.Header.Get("Retry-After")
      // 解析 Retry-After 并等待...
      time.Sleep(time.Duration(math.Pow(2, float64(i))) * time.Second)
      continue
    }
 
    // 服务器错误: 指数退避
    time.Sleep(time.Duration(math.Pow(2, float64(i))) * time.Second)
  }
 
  return nil, fmt.Errorf("max retries exceeded")
}

2. 优雅的错误处理


def call_api_safely(prompt):
    """安全调用API并处理所有错误"""
    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  # 设置超时
        )
 
        # 检查HTTP状态
        response.raise_for_status()
 
        # 解析响应
        data = response.json()
        return data['choices'][0]['message']['content']
 
    except requests.exceptions.Timeout:
        print("❌ 请求超时，请稍后重试")
        return None
 
    except requests.exceptions.HTTPError as e:
        # 解析错误响应
        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)
 
        # 根据错误类型处理
        if e.response.status_code == 401:
            print(f"❌ API密钥无效: {error_message}")
        elif e.response.status_code == 403:
            print(f"❌ 配额不足: {error_message}")
        elif e.response.status_code == 429:
            print(f"❌ 请求过于频繁: {error_message}")
        elif e.response.status_code == 404:
            print(f"❌ 资源不存在: {error_message}")
        else:
            print(f"❌ API错误 [{error_code}]: {error_message}")
 
        return None
 
    except requests.exceptions.ConnectionError:
        print("❌ 网络连接失败，请检查网络")
        return None
 
    except Exception as e:
        print(f"❌ 未知错误: {str(e)}")
        return None

3. 监控和日志记录


import logging
from datetime import datetime
 
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
 
def call_api_with_logging(prompt):
    """带日志记录的API调用"""
    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()
 
        # 记录成功请求
        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()
 
        # 记录失败请求
        logger.error({
            'event': 'api_call_failure',
            'error': str(e),
            'duration_seconds': duration,
            'prompt_length': len(prompt)
        })
 
        raise

错误排查清单

遇到错误时，请按以下清单逐项检查:

API密钥正确: 检查密钥格式、前缀和有效性
端点URL正确: 确认使用正确的基础URL和路径
请求格式正确: 验证JSON格式、必需参数和参数类型
模型名称正确: 查看可用模型确认模型名称
配额充足: 检查账户余额和可用配额
速率限制: 确认未超过速率限制
网络连接: 确保网络畅通，无防火墙阻拦
超时设置: 设置合理的超时时间(建议30-60秒)

获取帮助

如果按照上述指南仍无法解决问题:

💡 提示: 联系支持时，请提供完整的错误响应、请求示例（脱敏后）和时间戳，以便我们更快帮您解决问题。