错误码

多数情况下，请求失败时报错文案末尾会带一段括号，例如：

Request body exceeds the 32 MiB limit of the Messages API. Remove large images or documents from the conversation, or start a new conversation. (code: request_too_large, ref: jmds-3f2a9c1e7b4d4e8a9c216d5f0a8b2e47)

• code：错误码，在下面的表里查含义和处理办法。
• ref：这一次请求的编号，jmds- 加 32 位十六进制字符。联系支持时请完整复制它，我们能据此直接找到这次请求，不用再反复追问。

ref 在哪里找

• 报错 message 的末尾，括号里 ref: 后面的那一串；
• 响应头 X-Client-Request-ID。自己写代码调用接口时，报错文案没带 ref 也可以从响应头里取。

报障时请把 ref 连同发生时间、使用的客户端一起发给支持。

并不是所有报错都带 code

账户与风控类的报错（例如账号被临时限流、临时封禁或余额为负）由网关直接返回，错误码在响应正文的 code 字段里，message 末尾不带上面那段括号，见下方账户与风控类。

此外还有部分报错不带 code，按报错原文理解即可。

报错原句类

这类错误的 message 是官方原句（原样保留，不做改写），末尾追加 (code, ref) 后缀。表里的原句只是示例，具体字段名、数字、模型名以你实际收到的为准。

错误码	含义与处理
prompt_too_long HTTP 400	对话（提示词）的 token 数超过了所选模型的上下文上限。 处理：压缩上下文：Claude Code 里用 /compact；或用 /clear 开一个新对话；也可以删掉对话里体积很大的粘贴内容、文档和工具输出，或换用上下文窗口更大的模型。 示例原句：prompt is too long: 210000 tokens > 200000 maximum
unsupported_parameter HTTP 400	请求里用到的某个参数当前模型不支持，比如 effort（推理强度）、thinking 的某种设置、某类工具，或某种 tool_choice。报错原句里会写明是哪一项。 处理：按报错原句提示，去掉或调整该参数后重试；也可以换用支持该参数的模型。 示例原句：This model does not support the effort parameter.
invalid_field HTTP 400	请求体里带了接口不接受的多余字段。报错原句开头是字段路径，例如 messages.0.content.1.cache_control.scope。 处理：从请求里删除该字段。如果请求是客户端、SDK 或插件自动生成的，升级或更换到兼容的版本，或在其设置里关闭对应功能。 示例原句：messages.0.content.1.cache_control.scope: Extra inputs are not permitted
invalid_json HTTP 400	请求体不是合法的 JSON。 处理：检查代码里拼接请求体的地方（引号、逗号、转义、编码），确认发送的是合法 JSON，并带上 Content-Type: application/json。 示例原句：The request body is not valid JSON.
invalid_thinking_block HTTP 400	对话历史里的 thinking（思考）块校验不通过：签名无效，或者最近一条助手消息里的 thinking / redacted_thinking 块被改动过。 处理：不要手动编辑、截断或重排历史消息里的 thinking 块，要保持模型返回时的原样。如果客户端或脚本会改写历史，请去掉历史里的 thinking 块，或开一个新对话再试。 示例原句：messages.1.content.0: Invalid `signature` in `thinking` block.
long_context_unavailable HTTP 400	请求使用了长上下文（long context）beta，当前不可用。 处理：去掉长上下文相关设置（例如请求里的长上下文 beta 标识，或模型名里的 [1m] 后缀），把对话控制在标准上下文长度内；需要长上下文时带上 ref 联系支持。 示例原句：The long context beta is not yet available for this subscription.
model_not_found HTTP 404	请求的模型不存在，或当前不可用。报错原句里带有未找到的模型名。 处理：核对 model 字段的拼写，到控制台的模型列表确认可用的模型名，必要时换一个可用模型。 示例原句：model: claude-3-5-sonnet-20240620
domain_blocked HTTP 400	请求里要访问的网站（例如网页抓取类工具要读取的域名）不允许访问。报错原句里列出了对应的域名。 处理：换一个可访问的来源，或把内容直接贴进对话，不再让模型去访问这些域名。 示例原句：The following domains are not accessible to our user agent: example.org.

通用类

这类错误的 message 是固定的英文文案，下表逐字列出。

错误码	含义与处理
invalid_request HTTP 400	请求被判定为无效，报错里没有更具体的原因。 处理：检查请求参数：模型名、参数取值、消息格式是否正确；对话很长时用 /compact 压缩或新开对话再试。仍无法解决时，带上 ref 联系支持。 报错原文：The request was rejected as invalid. Check the request parameters and try again.
request_too_large HTTP 413	请求体超过 32 MiB 的上限。通常是对话里累积了大量图片、PDF 或长文档。 处理：移除对话中体积较大的图片或文档，或开一个新对话再试。Claude Code 可用 /clear 开新对话，或用 /compact 压缩。 报错原文：Request body exceeds the 32 MiB limit of the Messages API. Remove large images or documents from the conversation, or start a new conversation.
upstream_error HTTP 状态码不固定	请求未能完成。这是通用错误码：未能归入上面各类的部分失败会显示为它。 处理：稍后重试；持续出现请带上 ref 联系支持。 报错原文：The request could not be completed. Please retry later.

账户与风控类

这类错误在请求转发给模型之前就由网关直接返回，响应正文形如 {"code": "…", "message": "…", …}，code 就是下表的错误码，message 末尾不带 (code, ref) 后缀。message 里的数字和时间以你实际收到的为准；Gemini 原生接口（/v1beta）返回 Google 格式的错误，错误码在 error.details 里的 reason 字段。

错误码	含义与处理
VIOLATION_RATE_LIMITED HTTP 429	账号因当天计次违规达到阈值，被临时限流：并发和每分钟请求数被压低（默认并发 1、每分钟 10 次），超出的请求返回本错误。响应里的 throttled_until 是限流到期时间（UTC），rpm_limit 和 concurrency 是限流期间的上限；超过每分钟次数时还会带 Retry-After 响应头。 处理：降低请求频率和并发，按 Retry-After 退避后重试；到期会自动恢复。限流期间再次计次违规，限流会从那一刻起重新计时。认为是误判，带上被判违规请求的 request_id 联系支持。 详见：模型拒答与违规处理 示例：Your account is temporarily rate limited for repeated policy violations (10 requests per minute) until 2026-11-06T08:00:00Z. 示例：Your account is temporarily rate limited for repeated policy violations (1 concurrent requests) until 2026-11-06T08:00:00Z.
VIOLATION_SUSPENDED HTTP 403	账号因当天计次违规次数过多，被临时封禁（默认 24 小时）。封禁期间所有 API 请求都会直接被拒绝，不会发给模型，也不计费。响应里的 suspended_until 是解封时间（UTC），reason 是封禁原因。 处理：等待到期自动解封，控制台顶部的横幅会显示解封时间。认为是误判，带上被判违规请求的 request_id 联系支持，由人工复核。 详见：模型拒答与违规处理 示例：Your account is temporarily suspended for repeated policy violations (reason: violation_limit) until 2026-11-07T06:00:00Z.
NEGATIVE_BALANCE HTTP 403	账户余额为负数，常见原因是违规处理费从余额扣成了负数。余额为负期间所有请求都会被拒绝，订阅套餐的请求也一样。响应里的 balance 是当前余额。 处理：充值，把余额补到 0 或以上即可恢复。 详见：违规处理费与负余额 示例：Your account balance is negative (-0.40), which may include policy violation fees. Recharge to bring it back to zero or above to restore access.

流式响应中的错误

如果模型已经开始输出、中途才失败，HTTP 状态码已经是 200，错误会以流里的一条 error 事件出现，带 code 的流内错误文案格式相同，同样带 ref。按上表处理即可。

还是没解决？

请联系支持，并附上报错里的 ref、发生时间和使用的客户端。参见 常见问题。