2xx,客户端错误返回 4xx,服务端或上游错误返回 5xx。本页说明错误模型以及不同错误的处理方式。
错误响应结构
错误响应始终是包含error 对象的 JSON:
状态码
400:请求错误
400:请求错误
请求 Payload 格式错误,例如缺少必填参数、类型错误、JSON 无效或参数值超出范围。常见代码:
invalid_request、missing_parameter、invalid_parameter_type、json_parse_error处理方式: 修正请求后再试,不要自动重试。401:未授权
401:未授权
未提供 API Key、
Authorization 请求头格式错误,或密钥无效/已撤销。常见代码: missing_api_key、invalid_api_key、revoked_api_key处理方式: 在控制台中检查密钥,并使用 Authorization: Bearer YOUR_A...EY 重新发送请求。403:禁止访问
403:禁止访问
密钥有效,但无权访问该端点、模型或区域。常见代码:
insufficient_permissions、model_not_allowed、region_blocked处理方式: 检查工作区套餐和密钥权限范围。如果限制不符合预期,请联系支持团队。404:未找到
404:未找到
422:无法处理的实体
422:无法处理的实体
语法有效,但请求违反业务规则,例如
max_tokens 超过模型限制、参数组合不受支持,或内容违反上游提供商的安全策略。常见代码: max_tokens_exceeded、unsupported_parameter、content_policy_violation处理方式: 仔细阅读 message 并调整 Payload,不要盲目重试。429:请求过多
429:请求过多
500:内部服务器错误
500:内部服务器错误
AIsa 侧发生意外错误。
request_id 字段对于支持团队排查问题非常重要。处理方式: 使用指数退避重试。如果错误持续出现,请将 request_id 发送至 developer@aisa.one。502 / 503 / 504:上游错误
502 / 503 / 504:上游错误
AIsa 无法连接上游模型提供商(例如 OpenAI、Anthropic),或从上游收到错误。此类问题通常是暂时的。常见代码:
upstream_unavailable、upstream_timeout、gateway_error处理方式: 使用指数退避重试。如果问题持续出现,请切换备用模型;网关可以通过不同上游部署路由 Claude 请求。重试指南
1
只重试幂等或可安全重复的调用
所有
GET 请求和大多数聊天补全调用都可以安全重试。不要盲目重试会产生副作用的 POST 请求,例如发布推文。2
遵守 `Retry-After`
收到 429 响应时,始终遵守
Retry-After 响应头。收到未包含该响应头的 5xx 错误时,使用指数退避。3
使用带抖动的指数退避
从 1 秒开始,每次尝试将等待时间翻倍,并添加 ±25% 抖动,上限为 30 秒。
4
限制总重试时间
尝试 3–5 次或总计 60 秒后停止,以先到者为准,并将错误返回给调用方。
5
除 429 外,不要重试 4xx
400、401、403、404 和 422 表示请求本身存在问题,重试无法解决。最小重试示例(Python)
获取帮助
向 developer@aisa.one 报告问题时,请提供:- 错误响应中的
request_id - HTTP 状态码和
error.code - 模型 ID 和最小复现示例(使用已脱敏密钥的 cURL)
- 请求失败的大致时间