错误处理与重试

定位请求

保留请求时间和时区、HTTP 方法和路径、模型名称、API Key 前缀或 ID、HTTP 状态以及 x-cr-request-id；异步任务还要保存任务 id。每次轮询有独立的请求 ID，响应头始终标识当前 HTTP 请求。

请求和响应正文只保留脱敏后的必要片段。不要在工单或聊天中发送 Authorization Header、完整 API Key、客户输入或私有媒体 URL。

JSON HTTP 错误响应在顶层返回 request_id，与 error 并列，且与响应头 x-cr-request-id 一致。失败的异步任务也在顶层返回 request_id，但指向最初提交任务的请求。保存的结果不会随着轮询、幂等重试或回调改变；查询请求自身的 ID 仍从响应头读取。这些是 CR 标识，不是模型服务的原始 request ID。客户端如果只保存嵌套的 error 对象，会丢失 request_id。

旧任务已保存的终态正文不会补写新字段，客户端应兼容字段缺失。流内错误事件沿用原协议，关联 ID 从响应头读取。

响应含有 x-cr-usage-id 时也应保存，用它查询本次调用的账单。轮询请求的 request ID 可以变化，不能替代原始 usage ID。连接中断不代表免费，最终费用以账单的 billing_status: "final" 和 credits.after_discount 为准。

按阶段排查

错误响应格式

本页描述模型调用接口的错误。管理接口使用独立的错误格式，见管理 API。

模型调用的 HTTP 错误响应和异步任务终态使用相同的 error 对象。即时 HTTP 错误还会在 顶层返回 request_id，它与响应头 x-cr-request-id 相同：

{
  "error": {
    "type": "invalid_request_error",
    "code": "content_policy_violation",
    "message": "The request was rejected by a content safety filter"
  },
  "request_id": "0199c9e6-9381-7f30-9aa0-0df86dca6cdf"
}

请按 error.code 做分支。error.type 只作粗分类。除下文约定的上下文超限标识外，error.message 是可调整的可读文案，不要依赖完整措辞。

异步任务先按 status 判断是否结束：completed 为成功，failed 为失败。收到 failed 后停止轮询，再用 error.code 决定如何提示或处理；不要只在 error.code == "task_failed" 时才结束任务。GET 和 callback 使用同一份终态正文。其中的 id 是任务 ID；失败任务的 request_id 标识最初提交任务的请求，而非当前轮询。

来自模型的错误

HTTP 错误响应和异步任务终态中的模型失败使用下列 CR 错误码。错误码、错误类别和文案均由 CR 定义，不包含模型供应商的标识。流开始后的失败见流式过程中的错误。

已识别的错误会在 error.message 中提供纠错信息，例如被拒绝的字段、缺少的 schema 类型、素材大小上限或上下文 token 上限。能安全确定字段时，另有 error.param。错误说明不包含供应商身份、服务地址、凭据或原始请求内容。尚未识别的诊断保留通用说明，可通过 request_id 联系支持排查。

模型服务可能用 HTTP 400 报告模型离线。CR 保留该 HTTP 状态，但将错误归为 model_unavailable，而不是 invalid_parameter。不要仅凭 400 要求调用方修改生成参数，也不要无限重试。离线错误的提示不承诺模型会在短时间内恢复。

生成音频的版权审核失败

如果识别到生成音频的版权限制，error.code 仍为 content_policy_violation，error.message 会明确说明生成的音频可能触及版权限制。这不代表调用方上传了侵权音频；没有音频输入时，自动生成的音乐等内容也可能未通过审核。

可尝试关闭音频生成，或在模型支持参考音频时使用自有或已获授权的音频。具体写法见视频生成参数。这些调整不保证通过其他内容安全审核。如认为审核有误，请保留任务 id 和 request_id 联系支持。异步任务已返回 failed 时应停止轮询，不要无限重试生成。

上下文超限与客户端恢复

已识别的上下文窗口超限保留 error.type: "invalid_request_error" 和 error.code: "input_too_large"。文案以 prompt is too long 开头，供兼容客户端识别。如果能够取得实际输入 token 数和上限，CR 会同时返回这两个数字：

{
  "error": {
    "type": "invalid_request_error",
    "code": "input_too_large",
    "message": "prompt is too long: 1045171 tokens > 1000000 maximum; shorten or compact the conversation and retry"
  },
  "request_id": "0199c9e6-9381-7f30-9aa0-0df86dca6cdf"
}

CR 生成上述说明，不返回模型服务标识或原始诊断文案。图片、视频和 HTTP 请求体大小超限不使用这个上下文标识。

是否自动压缩仍取决于客户端版本、配置和会话状态，CR 不代替客户端压缩历史。如果 Claude Code 无法自动恢复，可使用 /compact 手动压缩，详见 Claude Code 网关排障说明。修改 max_tokens 不会删除已经包含在请求中的历史消息。

异步任务失败

异步任务终态（status: "failed"）使用同一套错误码，另有两个：

来自网关的错误

这些错误由 CR 自身产生，发生在调用模型之前，或替代了模型调用。

本地媒体参数校验失败使用 invalid_parameter，并保留可安全公开的原因。error.param 指向请求中的字段，例如 content[1].image_url.url、image[0] 或 provider_options.image_urls[0]。例如，只接受 HTTP(S) 媒体 URL 的模型收到 data URL 时，错误对象如下：

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "content[1].image_url.url: URL scheme must be HTTP(S) (url_kind=data); expected an HTTP(S) media URL",
    "param": "content[1].image_url.url"
  },
  "request_id": "01a09ec9-7d00-7000-8000-000000000001"
}

这类错误不回显原始 URL、签名参数、凭据、提示词或 Base64 内容。模型服务的错误只返回 CR 归类后的原因；无法安全确定具体字段时，param 可以省略。异步任务在收到 202 后也可能因本地参数校验变为 failed，应停止轮询并修正参数。

流式过程中的错误

流式响应一旦返回 200，CR 无法再改变状态码。连接仍可写入时，之后发生的失败会以流内的错误事件返回。客户端或代理已断开连接时，错误可能只记录在服务端，客户端无法再收到错误事件。

CR 在转发完整错误事件前，将模型的错误类别、错误码和文案替换为上方的 CR 错误码，不转发其诊断 URL、request ID 或调试字段。错误事件之前的正常输出保留；用量仍按已收到的有效用量结算。

事件结构随接口保持兼容：Chat Completions 和 Anthropic Messages 从 error.code 读取原因；Responses 的 error 事件从顶层 code 读取，response.failed 事件从 response.error.code 读取。所有这些事件都表示该流失败。

CR 生成的流式错误及服务端失败记录使用以下错误码：

流在缺少终止事件的情况下结束时，即使已收到部分内容也应视为失败，不要将部分内容标记为完整结果。中断前可能已经产生用量，最终费用以本次调用的账单为准。

有界重试

只对临时网络错误、429 和部分 5xx 进行有限重试。使用指数退避和随机抖动，并设置最大次数和业务截止时间。先修正认证、权限和参数错误，不要自动重试。

生成类 POST 超时不能证明任务未创建。直接重新提交可能创建重复任务并再次计费。

联系支持

如果问题仍未解决，向团队管理员或 CR 服务支持提供“定位请求”中的信息，并使用最小的脱敏输入复现问题。