错误

被拒绝的调用会返回与问题相符的 HTTP 状态码，以及统一的 JSON 结构：

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "The request payload failed validation.",
    "param": "text",
    "details": [{ "param": "text", "message": "String should have at least 1 character" }],
    "request_id": "c5a04c28ab76af26eb320eced12e30f0"
  }
}

字段	是否总有	含义
`type`	是	错误的大类，由 HTTP 状态码决定（见下）。
`code`	是	稳定的、供程序判断的错误码。请据此分支。
`message`	是	给人看的一句英文说明。可以展示或记录，但不要据此分支——措辞可能会变。
`param`	否	出错的请求字段（如有）：`422` 时一定有；其他针对单个字段的错误也会有，例如名称已被占用、文件过大。
`details`	否	仅 `422`：每个出错字段一条，含它的路径（`attachments[0].file_id`）和出错原因。
`request_id`	是	在我们日志里标识这次请求；也会通过 `X-Request-Id` 响应头返回。联系支持时请附上。

错误类型

`type`	HTTP 状态码
`authentication_error`	`401`：凭证缺失、无效、过期或已作废。
`permission_error`	`403`：凭证有效，但无权做这件事。
`rate_limit_error`	`429`：请求太多、同时进行的太多，或积分用完。
`api_error`	`5xx`：我们这边出了问题。
`invalid_request_error`	其他 `4xx`：这个请求本身无法处理。

错误码

错误码可能随时间增加。遇到不认识的错误码，按它的 HTTP 状态码大类处理。

状态码	错误码
`400`	`bad_request`
`401`	`invalid_secret`, `invalid_token`, `project_disabled`, `token_expired`, `user_disabled`
`403`	`permission_denied`, `project_disabled`, `user_disabled`
`404`	`file_expired`, `file_not_found`, `generation_not_found`, `not_found`, `project_not_found`, `session_not_found`, `user_not_found`
`405`	`method_not_allowed`
`409`	`call_in_progress`, `conflict`, `idempotency_conflict`, `idempotency_in_progress`, `session_busy`, `session_ended`, `session_not_realtime`, `session_not_taskable`
`410`	`endpoint_retired`：见版本与兼容
`413`	`file_too_large`, `payload_too_large`
`422`	`unsupported_media_type`, `validation_failed`
`429`	`insufficient_available_credits`, `insufficient_credits`, `rate_limited`
`500`	`internal`
`502`	`upstream_error`
`503`	`service_unavailable`

API 参考在每个接口上列出了它可能返回的状态码。

如何处理

401：换一个凭证。对用户令牌来说：签发新令牌（token_expired），或停止为该用户调用（user_disabled，以及作废后的 invalid_token）。
409 session_busy：这个会话里还有任务在运行。等它的结束事件，或先停止它，再重新发送消息。
409 idempotency_in_progress：带同一个 Idempotency-Key 的第一次请求还在处理中。按 Retry-After 响应头给出的秒数等待后，用同一个键重试同一个请求：它会返回第一次请求的答复。
409 idempotency_conflict：这个键已经用在了另一个请求上。不要重试：新的请求请换一个新的键。详见幂等。
429 rate_limited：按 Retry-After 响应头给出的秒数等待后重试。详见限流。
429 insufficient_credits：项目余额已用完。这种情况不带 Retry-After：在项目加上积分之前，重试也没有用。insufficient_available_credits 表示项目还有积分，但都被进行中的工作占用了。
5xx：用指数退避重试。对会启动工作的请求——消息、生成——请带上 Idempotency-Key，确保重试不会把工作启动两次。

已经开始的任务失败时，不会以 HTTP 错误返回，而是在事件流上用它的 task.failed 帧报告；详见事件流。

错误类型​

错误码​

如何处理​

错误类型

错误码

如何处理