Skip to content
使用 API

错误 ​

网关返回标准 HTTP 状态码。错误体的格式取决于错误发生在哪一层:认证层统一格式,接口层与所调用的协议保持一致。

错误体格式 ​

json
{
  "code": "INVALID_API_KEY",
  "message": "Invalid API key"
}
json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid days, allowed range is 1-90"
  }
}
json
{
  "error": {
    "type": "not_found_error",
    "message": "Images API is not supported for this platform"
  }
}

上游返回的错误会原样或按协议转换后透传,message 中可能包含上游的说明。

认证层错误码 ​

HTTPcode原因与处理
400api_key_in_query_deprecatedKey 放在了 URL 查询参数里。改用请求头,见认证。
401API_KEY_REQUIRED没有携带 Key。
401INVALID_API_KEYKey 不存在或已删除。
401API_KEY_DISABLEDKey 已在控制台被禁用。
401USER_INACTIVE账户已停用,联系管理员。
403API_KEY_EXPIREDKey 已过期,创建新 Key 或调整过期时间。
403INSUFFICIENT_BALANCE余额不足,充值后重试。
403SUBSCRIPTION_NOT_FOUND订阅分组下没有有效订阅。
403GROUP_NOT_ALLOWEDKey 所属的专属分组已不再对你开放。
429INVALID_AUTH_RATE_LIMITED短时间内多次使用无效 Key,稍后再试。
503API_KEY_AUTH_OVERLOADED认证服务暂时繁忙,可以重试。

接口层常见错误 ​

HTTPerror.type原因与处理
400invalid_request_error请求参数不合法,按 message 修正。
403insufficient_quotaOpenAI 协议下的额度不足。
404not_found_error当前分组平台不支持该端点,见协议与 Base URL。
429rate_limit_error触发上游或网关限速。
5xxapi_error上游暂时不可用。

重试建议 ​

  • 可以重试:429、500、502、503、529。使用指数退避,例如 1s、2s、4s,最多 3–5 次。
  • 不要重试:400、401、403、404。这些错误重试不会成功,需要先修正请求或账户状态。
  • 异步任务的提交请求不要自动重试,以免重复创建付费任务;先用任务 ID 查询状态。

排查时请提供 ​

联系支持时附上请求时间、使用的端点、模型 ID 和响应中的完整错误体。请勿发送完整的 API Key。