错误码参考

本文档列出了 nexusflow API 可能返回的所有错误码，以及推荐的处理方式。

HTTP 状态码

状态码	名称	可能原因	解决方案
`400`	Bad Request	请求格式错误必填参数缺失参数类型不匹配参数值超出有效范围	检查请求 JSON 格式是否正确，确认所有必填参数已提供且类型正确。
`401`	Unauthorized	API Key 无效或已过期未提供 Authorization 请求头认证格式错误	确认使用正确的 API Key，检查 Authorization 头格式为 'Bearer sk-air-xxx'。
`403`	Forbidden	账户余额不足 API Key 权限不足访问被禁止的资源账户被封禁	检查账户余额，确认 API Key 具有相应权限，联系客服处理账户问题。
`404`	Not Found	请求的模型不存在 API 端点路径错误资源已被删除	确认模型 ID 拼写正确，检查 API 端点路径，查看文档确认资源是否可用。
`413`	Payload Too Large	请求体超过大小限制上传文件过大 messages 数组过长	减少请求体大小，压缩或分割大文件，减少对话历史长度。
`422`	Unprocessable Entity	参数语义错误 temperature 超出 0-2 范围 max_tokens 超出模型限制	检查参数值是否在有效范围内，参考文档确认各参数的约束条件。
`429`	Too Many Requests	超出 RPM（每分钟请求数）限制超出 TPM（每分钟 Token 数）限制并发请求过多	实现请求重试机制（指数退避），升级套餐提高配额，优化请求频率。
`500`	Internal Server Error	服务器内部错误上游模型服务异常系统临时故障	稍后重试请求，如持续出错请联系技术支持。
`502`	Bad Gateway	网关错误上游服务不可达网络链路问题	稍后重试，检查服务状态页面，如持续出错请联系技术支持。
`503`	Service Unavailable	服务暂时不可用服务器过载维护中	等待几分钟后重试，关注官方公告了解维护计划。
`504`	Gateway Timeout	请求处理超时模型响应过慢网络延迟过高	减少 max_tokens 参数，简化输入内容，或稍后重试。

业务错误码

当请求失败时，响应体中会包含详细的错误信息：

{
  "error": {
    "code": "insufficient_quota",
    "message": "You have exceeded your quota. Please check your plan and billing details.",
    "type": "invalid_request_error"
  }
}

错误码	说明	解决方案
`invalid_api_key`	API Key 格式不正确或不存在	从控制台重新获取有效的 API Key
`insufficient_quota`	账户余额不足或配额已用完	充值账户余额或等待配额重置
`model_not_found`	指定的模型 ID 不存在	检查模型 ID 拼写，参考文档获取可用模型列表
`context_length_exceeded`	输入内容超出模型的上下文长度限制	减少输入内容长度，或使用支持更长上下文的模型
`content_filter`	内容因安全策略被过滤	修改输入内容，避免敏感或违规内容
`rate_limit_exceeded`	请求频率超出限制	降低请求频率，实现重试机制
`server_error`	服务器内部处理错误	稍后重试，如持续出错请联系支持

错误处理最佳实践

建议在生产环境中实现指数退避重试机制，以优雅地处理临时性错误：

from openai import OpenAI
import time

client = OpenAI(
    api_key="sk-air-your-key",
    base_url="https://nexusflow.hk/v1",
)

def call_with_retry(messages, max_retries=3):
    """带重试机制的 API 调用"""
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="claude-sonnet-4-6",
                messages=messages,
            )
            return response
        except Exception as e:
            error_code = getattr(e, 'status_code', None)
            
            # 可重试的错误
            if error_code in [429, 500, 502, 503, 504]:
                wait_time = (2 ** attempt) + 1  # 指数退避
                print(f"Error {error_code}, retrying in {wait_time}s...")
                time.sleep(wait_time)
                continue
            
            # 不可重试的错误
            raise e
    
    raise Exception("Max retries exceeded")

# 使用示例
try:
    response = call_with_retry([
        {"role": "user", "content": "Hello!"}
    ])
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Failed: {e}")

注意事项

可重试错误：429、500、502、503、504 通常是临时性问题，建议使用指数退避重试
不可重试错误：400、401、403、404、422 通常需要修改请求后才能成功
记录日志：建议记录请求 ID（响应头中的 X-Request-ID）以便排查问题
监控告警：建议对 5xx 错误设置监控告警，及时发现服务异常