5. 错误与限流

本端点错误响应采用 OpenAI 风格错误包。

5.1 错误包

{
  "error": {
    "message": "Invalid API key.",
    "type": "authentication_error",
    "code": "authentication_error",
    "param": null
  }
}

5.2 常见状态码

HTTP	error.type	说明
400	invalid_request_error	请求结构错误或参数不合法
401	authentication_error	鉴权失败
402	insufficient_balance	余额不足
403	permission_denied	无权限访问（例如 IP 不在允许列表）
404	model_not_found	模型不存在或不可访问
429	rate_limit_exceeded	请求频率超限
500	internal_error	服务内部错误
502	provider_error	依赖服务错误
503	provider_unavailable	服务暂不可用
504	provider_timeout	服务超时

5.3 常见错误示例

{
  "error": {
    "message": "invalid request: model is required",
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "param": null
  }
}

{
  "error": {
    "message": "invalid request: messages is required",
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "param": null
  }
}

{
  "error": {
    "message": "invalid request: messages[0].role is required",
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "param": null
  }
}

{
  "error": {
    "message": "this model does not support images/voices/videos/file_urls for this path",
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "param": null
  }
}

{
  "error": {
    "message": "invalid request: media_roles.images length must match images length",
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "param": null
  }
}

{
  "error": {
    "message": "this model is not available on this endpoint",
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "param": null
  }
}

{
  "error": {
    "message": "voices are not supported for multimodal text on this model",
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "param": null
  }
}

5.4 速率限制

本端点提供限速控制。请求可能同时受到以下三层频率限制约束：全局 QPS、按用户 QPM、按 API Key QPM。命中任意一层时，接口返回 HTTP 429，message 会说明命中的层级，例如：

{
  "error": {
    "message": "Global rate limit exceeded.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "param": null
  }
}

{
  "error": {
    "message": "User rate limit exceeded.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "param": null
  }
}

{
  "error": {
    "message": "API key rate limit exceeded.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "param": null
  }
}

说明：

• 响应头 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset 反映的是当前命中的限流层级的窗口信息，而不是所有层级的汇总值。
• 本文档当前未对基于 token 用量的限速（TPM）作出公开承诺；若后续新增，将在发布说明中同步更新。

建议使用指数退避策略重试：

初始等待: 1s → 2s → 4s → 8s（最多重试 4 次）