错误参考

标准化的错误格式及最常见的错误代码。

格式

无论是哪个端点，所有错误都遵循相同的 JSON 结构：

json

{
  "error": {
    "code": "insufficient_credits",
    "message": "Solde de credits insuffisant ou budget mensuel du projet depasse.",
    "request_id": "9480fe92-f68e-4731-b98e-d35a5e8b9819",
    "details": {}
  }
}

request_id 用于在各服务之间端到端地标识该请求——如果您因意外错误联系我们，提供该值会很有帮助。

常见错误代码

HTTP	代码	含义
401	missing_api_key	缺少 Authorization 请求头。
401	invalid_api_key	API 密钥无效、已被撤销或已过期。
403	insufficient_scope	该密钥不具备此类别所需的权限范围。
403	not_a_member	您不属于该组织。
403	csrf_check_failed	缺少安全请求头（会话 Cookie，不适用于 API 密钥调用）。
404	model_not_found	routing_strategy 为 "manual" 时使用了目录中不存在的 model。
404	no_model_available	没有模型符合所请求的条件。
402	insufficient_credits	账户额度余额不足，或项目月度预算已超支。
409	conflict	当前状态与请求的操作不兼容（例如智能体对话未处于 idle 状态）。
422	validation_error	请求体无效（缺少字段、类型错误等）。
429	rate_limit_exceeded	该密钥的请求过于频繁——参见速率限制。
503	all_providers_unavailable	所有候选供应商均调用失败（参见路由与故障转移）。

在 SDK 中

官方 SDK 会将每个 HTTP 状态码区间转换为一个类型化的错误类（AuthenticationError、PermissionDeniedError、NotFoundError、InsufficientCreditsError、ConflictError、ValidationError、RateLimitError、ServerError），它们除了错误消息外都暴露 .code、.status、.requestId 和 .details。参见 JavaScript SDK / Python SDK。