API 错误码参考

概述

本文档列出了 AutoBoxAPI 调用过程中可能返回的所有错误码、错误含义以及相应的解决方案。了解这些错误码有助于您快速诊断和解决 API 调用中遇到的问题。

HTTP 状态码

2xx 成功状态码

状态码含义描述
200OK请求成功
201Created资源创建成功
202Accepted请求已接受，正在处理

4xx 客户端错误

400 Bad Request - 请求参数错误

常见原因:

  • 请求体格式不正确
  • 缺少必需参数
  • 参数类型错误
  • 参数值超出允许范围

错误示例:

{
  "detail": "请求参数错误：messages 字段不能为空"
}

解决方案:

  1. 检查请求体是否为有效的 JSON 格式
  2. 确认所有必需参数都已提供
  3. 验证参数类型和值是否符合 API 规范
  4. 参考 API 文档确认正确的参数格式

401 Unauthorized - 未授权访问

常见原因:

  • 缺少 Authorization 头
  • API_KEY 格式错误
  • API_KEY 无效或已过期
  • Bearer Token 格式不正确

错误示例:

{
  "detail": "缺少Authorization header"
}

{
  "detail": "Authorization header格式错误"
}

{
  "detail": "Token验证失败"
}

解决方案:

  1. 确保请求头包含正确的 Authorization 字段
  2. 验证 API_KEY 格式：Bearer ak-32位字符
  3. 检查 API_KEY 是否有效且未过期
  4. 重新生成新的 API_KEY

403 Forbidden - 访问被拒绝

常见原因:

  • 用户账户被禁用
  • 用户账户已过期
  • API_KEY 状态为禁用
  • 权限不足
  • IP 地址被限制

错误示例:

{
  "detail": "该用户已被禁止登陆"
}

{
  "detail": "该用户已过有效期"
}

{
  "detail": "提供的API-KEY无效或缺失"
}

解决方案:

  1. 检查用户账户状态
  2. 确认账户是否在有效期内
  3. 验证 API_KEY 状态是否为"启用"
  4. 联系管理员检查权限设置
  5. 确认请求来源 IP 是否被允许

404 Not Found - 资源不存在

常见原因:

  • API 端点路径错误
  • 资源 ID 不存在
  • 应用 ID 无效

错误示例:

{
  "detail": "API Key不存在"
}

{
  "detail": "任务不存在"
}

解决方案:

  1. 检查 API 端点 URL 是否正确
  2. 验证资源 ID 是否存在
  3. 确认应用 ID 是否有效

422 Unprocessable Entity - 数据验证失败

常见原因:

  • 请求数据格式正确但内容无效
  • 字段值不符合验证规则
  • 数据类型转换失败

错误示例:

{
  "detail": [
    {
      "loc": ["body", "temperature"],
      "msg": "ensure this value is less than or equal to 2",
      "type": "value_error.number.not_le",
      "ctx": {"limit_value": 2}
    }
  ]
}

解决方案:

  1. 检查字段值是否符合验证规则
  2. 确认数据类型是否正确
  3. 参考 API 文档了解字段限制

429 Too Many Requests - 请求过于频繁

常见原因:

  • 超出 API 调用频率限制
  • 超出配额限制
  • 并发请求数过多

错误示例:

{
  "detail": "API调用频率超出限制，请稍后重试"
}

{
  "detail": "配额不足，无法继续调用"
}

解决方案:

  1. 实现请求限流机制
  2. 增加请求间隔时间
  3. 使用指数退避重试策略
  4. 考虑升级配额或购买更多额度
  5. 优化请求逻辑，减少不必要的调用

5xx 服务器错误

500 Internal Server Error - 服务器内部错误

常见原因:

  • 服务器内部异常
  • 数据库连接失败
  • 第三方服务不可用
  • 代码逻辑错误

错误示例:

{
  "detail": "任务执行失败: 内部服务器错误"
}

{
  "detail": "创建失败: 数据库连接超时"
}

解决方案:

  1. 稍后重试请求
  2. 检查请求参数是否正确
  3. 联系技术支持报告问题
  4. 实现重试机制处理临时错误

502 Bad Gateway - 网关错误

常见原因:

  • 上游服务不可用
  • 代理服务器配置错误
  • 网络连接问题

错误示例:

{
  "detail": "代理请求失败: 上游服务不可用"
}

解决方案:

  1. 稍后重试请求
  2. 检查网络连接
  3. 联系技术支持

503 Service Unavailable - 服务暂时不可用

常见原因:

  • 服务器维护
  • 系统过载
  • 临时性故障

错误示例:

{
  "detail": "服务暂时不可用，请稍后重试"
}

解决方案:

  1. 等待一段时间后重试
  2. 实现降级策略
  3. 关注服务状态公告

504 Gateway Timeout - 网关超时

常见原因:

  • 请求处理时间过长
  • 上游服务响应超时
  • 网络延迟过高

错误示例:

{
  "detail": "请求超时，请稍后重试"
}

解决方案:

  1. 增加客户端超时时间
  2. 对于长时间任务使用异步接口
  3. 优化请求参数减少处理时间
  4. 实现超时重试机制

业务错误码

认证相关错误

错误信息原因解决方案
"该用户不存在，token无效"用户 token 无效重新登录获取有效 token
"该用户已被禁止登陆"用户账户被禁用联系管理员解除限制
"该用户已过有效期"用户账户已过期续费或联系管理员延期
"该APIKEY不存在，验证失败"API_KEY 不存在检查 API_KEY 是否正确
"api_key验证失败"API_KEY 验证失败重新生成或检查 API_KEY

任务执行错误

错误信息原因解决方案
"任务执行失败"任务处理异常检查请求参数，稍后重试
"代理请求失败"上游服务异常稍后重试或联系技术支持
"任务超时"任务执行时间过长使用异步接口或优化参数
"配额不足"API_KEY 配额用完充值或购买更多配额
"并发限制"超出并发请求限制减少并发请求数量

数据验证错误

错误信息原因解决方案
"messages 字段不能为空"缺少必需参数提供正确的 messages 参数
"model 参数无效"模型名称错误使用支持的模型名称
"temperature 值超出范围"参数值超出限制设置 0-2 之间的值
"max_tokens 必须为正整数"参数类型错误提供正整数值

错误处理最佳实践

1. 错误分类处理

def handle_api_error(response):
    status_code = response.status_code
    
    if status_code == 400:
        # 客户端错误，检查请求参数
        print("请求参数错误，请检查输入")
    elif status_code == 401:
        # 认证错误，重新获取 token
        print("认证失败，请检查 API_KEY")
    elif status_code == 403:
        # 权限错误，检查账户状态
        print("访问被拒绝，请检查权限")
    elif status_code == 429:
        # 限流错误，实现重试
        print("请求过于频繁，等待后重试")
    elif status_code >= 500:
        # 服务器错误，稍后重试
        print("服务器错误，稍后重试")

2. 重试机制

import time
import random

def api_call_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise e
            
            # 指数退避
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait_time)

3. 日志记录

import logging

def log_api_error(error_response):
    logging.error(f"API调用失败: {error_response.status_code} - {error_response.text}")

4. 用户友好的错误提示

def get_user_friendly_message(error_code):
    error_messages = {
        400: "请求参数有误，请检查输入内容",
        401: "身份验证失败，请检查API密钥",
        403: "访问权限不足，请联系管理员",
        429: "请求过于频繁，请稍后再试",
        500: "服务暂时不可用，请稍后重试"
    }
    return error_messages.get(error_code, "未知错误，请联系技术支持")

联系支持

如果您遇到文档中未涵盖的错误，或需要进一步的技术支持，请：

  1. 查看系统状态: 访问状态页面了解服务可用性
  2. 搜索文档: 在文档中搜索相关错误信息
  3. 联系技术支持: 发送邮件至 support@autonav.com
  4. 提供详细信息: 包括错误码、请求详情、时间戳等

在联系支持时，请提供以下信息：

  • 完整的错误响应
  • 请求的详细信息（去除敏感数据）
  • 发生错误的时间
  • 您的用户 ID 或 API_KEY ID（前几位字符）