Kimi 错误码对照与处置：401/403/429/504 分别怎么查

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

看 Kimi API 的报错，只盯着 HTTP 状态码基本查不出问题。 官方错误响应是一个 JSON，结构固定为 error.type 和 error.message 两个字段，真正决定处置动作的是 type。同一个 429 底下挂着三种完全不同的 error.type，一种要退避重试、一种要降并发或提等级、一种要去看余额；同一个 401 可能是 Key 写错了，也可能是 Key 属于另一个平台或另一个产品。反过来，有些看起来像故障的现象（内容被截断、Agent 没显示结果却扣了费）在官方文档里压根不算错误码，得换一套查法。下面按官方《常见错误码说明》和《问题排查》两页的原文，把每一类拆开讲。

先把错误响应的结构认清

官方文档给出的失败响应示例是这样一个结构：顶层一个 error 对象，里面有 type 和 message。文档同时给了一段不使用 SDK 时的处理范式：用 HTTP 200 表示成功，4xx、5xx 表示失败，失败时从 r.json() 里取 error['error']['type'] 和 error['error']['message'] 再决定后续逻辑——记日志、中断请求还是重试。

这个范式值得原样抄进你的封装层：官方示例里的错误分支不是只打一个状态码就完事，而是把 type 和 message 一起取出来再决定走哪条路。自己对接 HTTP 时请务必把 type 打进日志，否则收到 429 只能靠猜。至于使用 OpenAI SDK 时这个字段会以什么形式暴露在异常对象上，官方文档里没有找到相关说明——如果你走的是 SDK 路线，建议先把一次完整异常原样打印出来，确认 type 到底能不能取到，再据此决定日志字段怎么埋，而不是照着别的服务商的经验想当然。另外官方在多处反复要求排查时提供 request_id，这个值也应该跟着每一条错误日志一起落盘，后面找支持团队查账时是硬通货。

401 与 permission denied：先判 Key 属于哪个平台、哪个产品

401 在官方表里有两个 error.type：invalid_authentication_error（典型 message 是 Invalid Authentication，表示 API Key 无效或格式错误，要检查 Authorization: Bearer <key> 的写法）和 incorrect_api_key_error（未提供 Key 或 Key 错误）。

但官方并没有让这张表说完，而是在 401 表格下面单独挂了一段「平台 Key 隔离说明」，在《问题排查》里又用一整条问答重复了一遍：中国站与国际站是两套独立的账户、余额和 API Key，混用会返回 401。官方明确写了国内开放平台的 base_url 是 https://api.moonshot.cn/v1，境外开放平台是 https://api.moonshot.ai/v1，境内建议用中国站、境外建议用国际站，两边的账户和 key 完全独立不能混用。

在这之上还有一层产品隔离：Kimi API 开放平台、Kimi Code、Kimi 会员是三个相互独立的产品，付费方式、余额权益和 API Key 都不通用；Kimi 会员的订阅权益不会转成开放平台余额，开放平台的余额也不能拿去买会员或 Kimi Code Plan。把别的产品的 Key 填到开放平台端点上，官方说会出现 401 或 404。

官方给的排查顺序是有讲究的，照着走能省很多时间：先确认 Key 是不是来自你正在调用的那个产品，再确认 Key 所属区域与调用端点是否一致，然后看账户是否有可用余额、代金券是否支持目标模型，接着用同一个 Key 调 GET /v1/models，确认目标模型在不在返回列表里，最后清理旧的环境变量、代理以及 CC Switch 之类本地路由中的旧配置，确认实际生效的 Key 与端点。官方把清理旧配置这一步放在整个排查顺序的末位，指向的正是「配置改了、实际生效的还是旧的」这种情形：环境变量、代理、CC Switch 之类的本地路由都可能在你不知情的时候接管请求，而报错本身只会告诉你鉴权没过，不会告诉你请求实际发去了哪里。这一步的动作也很明确——不要看配置文件里写了什么，要看请求真正带出去的 Key 与端点是什么。

还有一个模型名的坑：官方说直接调 API 和在 Codex 中使用某个模型名、在 Claude Code 中使用带兼容别名后缀的写法，三者可能不同，要以对应接入教程为准。也就是说同一个模型在不同宿主里的字面写法未必一致，照抄别处的配置就可能 404。关于端点与 Key 的基础配置，可以先过一遍Kimi API 接入步骤。

403 的三种权限拒绝各指一件事

403 在官方表里统一是 permission_denied_error，但三条 message 指向三件完全不同的事：

• The API you are accessing is not open —— 该 API 暂未对当前账号开放；
• You are not allowed to get other user info —— 不允许访问其他用户信息，要检查接口权限范围；
• Your IP is not allowed to access this organization —— 调用 IP 不在组织白名单内，官方注明这在国际站比较常见，需要联系管理员把 IP 加进去。

第三条对做迁移的团队特别值得留一眼：官方把它归到权限问题而不是鉴权问题，说明 Key 本身是对的、只是发起调用的地址不被组织接受。所以本地正常、换到云上或换了机房就 403 的时候，先别翻代码，去确认服务的出口 IP 是什么、在不在组织白名单里，弹性伸缩和 NAT 网关都会让这个地址跟你以为的不一样。

400 家族：内容安全与请求体两条线

400 底下第一类是 content_filter，典型 message 是 The request was rejected because it was considered high risk。官方特意提醒：不只是你的输入，模型生成的内容也可能包含敏感内容进而触发这个错误，所以不能只检查提示词。文档还说明平台无法提供具体命中的安全策略规则，能做的是缩小请求范围、移除可能引起误判的内容后重试。如果你是通过第三方平台或工具调用的，还要先确认这条错误确实来自 Kimi API——第三方平台可能有自己的内容安全策略和错误话术。

第二类是 invalid_request_error，覆盖了请求体的各种问题：请求格式错误、缺少必填参数或参数类型非法；输入 tokens 超过模型最大上下文限制（message 是 Input token length too long）；prompt tokens 与 max_tokens 之和超过模型规格；文件上传时 purpose 字段不正确，官方说明当前仅接受 file-extract；上传文件超过官方规定的单文件大小上限；上传文件大小为 0（要检查文件是否损坏或为空）；以及上传文件总数超过上限，需要删掉不再使用的早期文件再重试。

这一族的排查动作很统一：对照接口文档逐字段核请求体。要提前避开 token 超限，官方推荐的做法是先用 estimate-token-count 接口算出输入 tokens，再从所选模型支持的最大上下文窗口里扣掉这部分，剩下的值作为本次请求 max_completion_tokens 的上限。

429 是三种病共用一个号

官方在《问题排查》里为 429 单独立了一条问答，标题就叫「为什么充值后仍然返回 429」——把这个疑问单独列出来本身就是一种提示。答案是 429 不是单一原因，必须先看 error.type，官方错误码表里挂在 429 下面的正是这三类：

• engine_overloaded_error：服务节点负载较高（比如高峰期容量压力）。处置是按响应中的 Retry-After 提示等待、降低并发并使用指数退避重试。官方明确写了这个错误由服务端容量导致，充值或提升 Tier 不能直接消除——这句话很重要，很多人一收到 429 就去充值，方向就错了。
• rate_limit_reached_error：触发组织级限速，具体又分并发、RPM（每分钟请求数）、TPM（每分钟 token 数）、TPD（每日 token 数）四种。前两种降低并发或按提示等待，TPM 类降低调用频率或升级 tier，TPD 类次日恢复或升级套餐。
• exceeded_current_quota_error：账户欠费、停用、余额不足或代金券失效。官方建议先通过查询余额接口确认 available_balance 再决定是否充值。

还有两条附带信息值得记住。一是因 429 错误中断的请求不会扣费，官方原文如此，遇到大面积 429 时不必担心账单被这些失败请求撑大。二是客户端自动重试会放大请求数：OpenAI SDK 等客户端默认会自动重试，连接错误、408、409、429 以及 5xx 都在默认重试范围内，一次操作可能变成多次请求并占用限速额度；官方甚至指出，对于使用 OpenAI SDK 且账户等级为 tier0 的用户，由于存在默认的重试机制，一次错误的请求就会把 RPM 额度消耗完。所以排查限速问题时，要去看客户端日志里的实际请求次数，而不是你以为发了几次。

官方还单独列了一条问答，讲报错信息里的 TPM、RPM 限制与后台看到的账户等级对不上该怎么办。给出的判断是：这种不匹配通常是用错了 api_key，比如误用了别人给的 key，或者个人有多个账号时把 key 混用了。限速的通用机制可以参考API 限流 RPM 与 TPM，通用退避写法见429 错误的通用处理。

499 / 500 / 503 / 504 与 Connection 错误

这一组在官方表里按 HTTP 状态码列：

• 499 client_closed_request：客户端在服务端返回前断开连接，常见于流式响应被中间代理切断或用户主动取消，要检查 KeepAlive 与超时设置；
• 500 server_error 或 unexpected_output：服务端内部错误，稍后重试；若持续出现，官方要求附带 request_id 联系支持团队 api-service@moonshot.ai；
• 503 server_unavailable：服务暂时不可用，官方说通常与节点扩容或维护有关；
• 504：服务端长时间无响应后网关返回 HTML 超时页面，官方注明常见于非流式长请求，建议改用流式输出 stream: true。

504 返回的是 HTML 而不是 JSON 这一点值得单独防一手：如果你的错误处理代码无脑 r.json()，在 504 上会直接抛解析异常，把真实原因掩盖掉。

Connection 相关错误官方给了固定的三步检查：程序代码或 SDK 是否有默认的超时设置；是否使用了代理服务器以及代理的网络与超时设置；以及最隐蔽的一种——未启用 stream=True 时模型生成的 tokens 数量过多，服务端要等生成完毕才发送 header，而某些网关通过检测是否收到 status_code 和 header 来判断请求是否有效，等待过久就会把连接关掉。官方的推荐是启用流式输出来尽量减少这类错误。

那些不是错误码、但一样会被当成故障的现象

内容被截断：先看响应体里 choice.finish_reason 的值，如果是 length，说明生成内容的 tokens 数超过了请求里的 max_completion_tokens，超出部分会被丢弃。想接着上次的内容往下写，官方提供了 Partial Mode；想避免截断，就适当增大 max_completion_tokens。顺带一提，官方注明 max_tokens 已弃用，请改用 max_completion_tokens，两者含义相同。官方还澄清了一个常见误解：max_completion_tokens 不会作为提示词的一部分输入模型，它只是一个上限闸门，指望靠它控制输出字数是不成立的。

模型反复调用同一个工具：官方给的判据是 function.name 与 function.arguments 完全相同、且工具返回结果没带来新的有效信息。排查顺序是先看消息布局：返回 finish_reason=tool_calls 时有没有把 choice.message 原封不动加回 messages；每个 tool_call 是否都有一条对应的 role=tool 消息；role=tool 里的 tool_call_id 是否与 tool_call.id 完全一致；用流式输出时分片返回的 tool_calls（尤其是 function.arguments）有没有正确拼接。布局没问题再考虑在业务侧做重复检测并在系统提示词里追加提醒。

model_not_found：官方说这个错误通常是使用 OpenAI SDK 时没设 base_url，请求被发到了 OpenAI 服务器，由 OpenAI 返回的。也就是说这条报错很可能根本不是 Kimi 发出来的。

客户端没结果却产生了费用：官方明确写了客户端没显示结果不代表请求失败——编程工具等待时间过短、代理连接断开或本地超时都会让客户端停止展示，而服务端请求可能已经完成并产生调用记录。检查顺序是：HTTP 状态码与 request_id、响应里的 usage 字段、客户端是否自动重试或启动子 Agent 循环调用工具、控制台的用量看板与计费明细、客户端日志中的超时和连接错误。日常的用量核对方法可以参考API 成本监控。

第三方工具报错时，先把链路拆两层

用 Claude Code、Codex、OpenCode、CC Switch、Trae 这类工具接 Kimi 出问题时，官方给的方法是把链路拆成 Kimi API 与第三方工具两层：用相同的 Key、端点和模型直接调 API；直连就失败，说明是余额、鉴权、模型权限或请求参数的问题；直连成功而工具失败，就去看工具日志，重点查协议转换、流式响应、超时设置和自动重试。官方还提醒 CC Switch、Trae 等第三方工具不由 Kimi 开放平台维护，这种情况需要同时联系对应工具的支持渠道。

要提交给平台的材料清单官方也列了：组织 ID、项目名称、发生时间（含时区）、request_id、模型名、客户端与版本、脱敏日志、相关账单或导出记录，走 API 问题反馈表单提交。这份清单本身就是一份排查提纲——如果这些你一条都拿不出来，说明日志埋点还不够。

把三件事固定进代码里

把上面这些串起来，有三处值得在写排查逻辑时就固定下来。第一，只看状态码不看 error.type，429 尤其如此——官方明确写了节点过载这一类由服务端容量导致，充值或提升 Tier 不能直接消除，所以状态码相同、处置动作完全相反。第二，平台与产品之间的隔离是官方反复强调的一条：国际站的 Key 打到中国站端点、Kimi Code 的 Key 填进开放平台，都会以 401 或 404 的面目出现，而报错本身不会告诉你「你拿错平台了」，只能靠自己在排查清单里先把这一条勾掉。第三，把客户端的自动重试当成一次请求来算账，限速额度和实际请求次数从此对不上，官方为此专门提醒排查时要去看实际请求次数和客户端日志。

下一步的动作很具体：在你的调用封装里把 request_id、error.type 和 usage 三个字段固定写进日志，非流式的长请求改成流式，然后按 error.type 分支写重试策略——只有 engine_overloaded_error 和 5xx 值得退避重试，exceeded_current_quota_error 和 400 家族重试多少次都不会变好。