MiniMax 限流机制与错误码对照：报错先看哪一层
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
排查 MiniMax 的报错，第一步不是查错误码表，而是先确认这个错误是从哪一层返回的。 同一个平台上，OpenAI 兼容风格的对话接口把错误塞在响应体的 base_resp 里、HTTP 层看不出异常；Anthropic 兼容接口用的是 HTTP 状态码加 JSON 错误体这一套；Responses 接口则只在 status=failed 时才带 error 字段。三条路的错误形态完全不同，用错了判断方式，你会得到”接口返回 200 却没有内容”这种看起来毫无头绪的现象。限流这一侧同样不止一个维度：官方明文的限速维度是 RPM 和 TPM，视频与音乐类接口另有 CONN（最大并行运行任务数），Token Plan 订阅链路还叠了一层窗口额度控制。下面按真实排查顺序走一遍。
第一步：确认错误是从哪一层冒出来的
MiniMax 语言模型官方给了三种接入形态，可以走 HTTP 请求，也可以用 Anthropic SDK 或 OpenAI SDK。这三种形态的错误返回位置不一样，所以排查的第一个动作是先认清自己走的是哪条链路。
OpenAI 兼容的对话接口，响应体里有一个 base_resp 对象，官方对它的描述是”错误状态码和详情”，内部两个字段：status_code（状态码）和 status_msg（错误详情）。官方给出的成功响应示例里，status_code 是 0、status_msg 是空字符串。也就是说，判断这条请求成不成功，你要读的是响应体里的这个数字，而不是 HTTP 状态。这份接口文档在响应部分只给出了 200 这一档的定义，错误详情则落在 base_resp 这个对象里，所以客户端不能只靠 HTTP 状态码分流。
Anthropic 兼容接口是另一套。官方对错误响应的说明写得很直白：统一使用 HTTP 状态码加 JSON body。错误体结构固定为 type（固定取值 error）、request_id（本次请求的唯一标识，便于排查问题）和 error 对象，error 里再分 type 和 message。这里的 error.type 是一个枚举，官方列出的取值有 invalid_request_error、authentication_error、permission_error、not_found_error、request_too_large、rate_limit_error、api_error、overloaded_error（枚举以官方文档为准）。还有一条容易被忽略的说明：流式过程中出现错误时，会以 event: error 这个 SSE 事件下发，body 结构与非流式一致，官方明确要求客户端在收到 error 后停止读取并清理本次会话状态。很多自己撸的流式解析器只处理 message_stop，碰到中途报错就会挂在那里等一个永远不来的结束事件。这一层的接入细节可以配合 MiniMax 的 Anthropic SDK 接入方式 一起看。
Responses 接口是第三种：响应里有 status（响应状态）字段，error 对象被标注为可空，官方说明是”仅在 status=failed 时返回”，内部是 code（错误码）与 message（人类可读的错误描述）。所以对这条链路，判断成败要先读 status。
第二步：搞清楚限流是按什么维度算的
官方速率限制页给的定义很清楚：RPM 是每分钟发送的请求数限制，TPM 是每分钟输入加输出的 token 数限制。注意 TPM 把输出也算进去了，这意味着一个爱刷长输出的任务，即使请求数不高也可能先撞 TPM。
有三个结构性事实值得记住。第一，限速是按模型和接口分别设定的，语言、视频、语音、图片、音乐几类接口各有各的表，并且区分免费用户与充值用户两档，具体数值请以官方速率限制页当前版本为准。第二，视频与音乐接口除了 RPM，还有一个叫 CONN 的维度，官方括号里写明是”最大并行运行任务数”——这类异步生成任务卡住时，往往不是请求发多了，而是同时在跑的任务太多。第三，官方在速率限制页专门用一整节说明限速策略施加在你的账号上，且明确包含主账号加子账号，主子账号共同享有这些限制。官方还举了例子说明这个共享逻辑——主账号用掉的额度会直接从子账号可用的那部分里扣。所以拿子账号做”分流”是无效的。
官方还给了一条实操建议，方向和很多人的直觉相反：由于每分钟请求数和每分钟 token 数是分开限制的，如果 RPM 已经打满但 TPM 还有余量，官方建议把多个任务批量放进一个请求里，从而提高 token 吞吐。也就是说撞 RPM 时该做的是合并请求而不是加机器。关于这两个维度的通用取舍，可以对照 RPM 与 TPM 限流的通用机制 来读。
第三步：把限流类错误码认全
限流不是只有一个码。MiniMax 错误码查询页里，跟”发太快”沾边的至少有四个，含义各不相同：
1002请求频率超限，官方给的解决方法是稍后再试。这是最标准的那一种。2045请求频率增长超限，官方解决方法写的是”请避免请求骤增骤减情况”。照这句官方措辞理解，它约束的不是总量而是变化幅度：从静默状态突然把并发拉满，即使平均值没超也可能触发。压测脚本和集中在整点触发的定时任务，正是会造出这种骤增曲线的两类场景，安排的时候把起量做平缓一些。1041连接数限制，官方给的解决方法只有一句”请联系我们”——错误码查询页没有再展开这个”连接数”具体指什么。需要留意的是，Anthropic 兼容接口对 429 的官方描述里同样列了”连接数”这一类限流，而速率限制页把 CONN 注为”最大并行运行任务数”、只出现在视频与音乐两张表里。这两处的”连接数”是不是同一个口径，官方文档里没有找到相关说明，所以不要想当然地拿视频那张表的并行任务数去套语言模型链路。碰到1041，能做的动作就是按官方说的走客服通道，同时先把自己这边的长连接与并发数降下来观察。2056超出 Token Plan 资源限制，官方解决方法是等待下一个时间段资源释放后再次尝试。这一条只出现在订阅链路上，跟按量付费的限速不是一回事。
在 Anthropic 兼容接口那一侧，这些情况会以 HTTP 429 出现，官方对 429 的描述是”触发 RPM/TPM/连接数 等限流”，错误类型是 rate_limit_error。另外注意 529 这一档，官方描述是上游模型过载、可重试，类型 overloaded_error——它和 500（api_error，服务端内部错误）不同，官方明确标了可重试。退避重试的通用写法见 429 该怎么处理。
至于怎么把限速提上去：官方文档说的是通过页面底部的官方客服或官方邮箱提交提高速率限制的申请，并且提示审批需要若干个工作日，建议在产品上线前尽早提交。文档里没有给出任何自助调整入口。
第四步：非限流类的高频码怎么分辨
鉴权这一类有两个码，含义不完全重叠。1004 官方写的是”未授权/Token 不匹配/Cookie 缺失”，解决方法是检查 API Key；2049 是”无效的 API Key”。两者都指向密钥，但前者的表述覆盖了更多凭证异常场景。排查时有一个容易被跳过的前提是确认 Key 拿对了没有：官方明确说明按量计费 API Key 与 Token Plan 订阅 Key 是两套、相互独立，并且在 FAQ 里专门设了一条问答回答”能不能混用”——不可以。也就是说，Key 本身没过期、账户也有余额，只要用错了体系一样会撞到鉴权类错误码，而报错文案不会告诉你是这个原因。密钥本身的管理规范见 API Key 安全管理。
1008 是余额不足。这条与其等它报出来，不如提前配好预警：官方 FAQ 建议开启余额预警功能，在账户管理的余额页设置预警值，低于该值时平台会通过邮件、短信、站内信等形式通知。
内容安全这一类是 1026（输入内容涉敏）和 1027（输出内容涉敏）。这里有个官方文档自身的细节：1027 明明是输出侧命中，但官方给的解决方法写的仍然是”请调整输入内容”——从工程角度也说得通，输出是输入引出来的，你能改的只有输入。对话接口的响应里还有配套字段可用：input_sensitive 与 output_sensitive 是布尔值，input_sensitive_type 会在命中时返回一个整型的命中类型，官方列出的取值包括严重违规、色情、广告、违禁、谩骂、暴恐、其他这几类（以官方文档为准）。官方还说明，如果内容严重违规，接口会返回内容违规错误信息、回复内容为空——这正是”200 但没内容”的一种成因。
参数类的两个码：2013 参数错误，检查请求参数即可；1039 是 Token 限制，官方给的解决方法很具体，是让你调整 max_tokens，而不是去缩短输入。
还有一个对不上的地方值得提前知道：OpenAI 兼容接口 schema 里对 status_code 的说明只列了一个子集，其中把 1013 标为服务内部错误；而错误码查询页的完整表里并没有 1013，列的是 1024（内部错误）和 1033（系统错误/下游服务错误）。两份清单不完全一致，做错误码映射表时以错误码查询页为准，并且给未知码留一个兜底分支。
第五步：Token Plan 链路的限流是另一套逻辑
如果你的 Key 是订阅 Key，限流规则要多看一层。官方 FAQ 里说明，Token Plan 的限制主要包括两块：一是速率限制（RPM / TPM），超出后会限流、短时间内恢复，高峰期可能动态收紧；二是套餐内额度，受 5 小时窗口和周窗口控制（窗口口径以官方文档当前版本为准），未使用完的套餐内额度不会结转到下一个计费周期。
平台流量规则那一节还说明，MiniMax 可能在高峰时段实施动态限流，高峰时段根据集群负载动态调整，官方给出的参考区间落在工作日下午。理由官方也写了：部分请求来自超高并发自动化批量任务或多用户共享模式，平台会基于账户使用维度进行速率调控。
撞到额度上限时，官方列的出路有四条：用已购积分自动补充支付、升级订阅套餐（升级后立即生效）、把工具里的订阅 Key 换成普通开放平台 API Key 转为按实际 token 用量计费、或者等窗口滚动自动恢复。最后还有一句定位很明确的话——官方说 Token Plan 面向个人开发者的交互式使用场景，生产环境建议使用按量付费。如果你的服务是线上跑批，别在订阅链路上死磕限流。
最后：留好 trace_id 和 request_id
错误码查询页开头有一条提示：如需反馈问题，请提供 Header 中的 trace_id，以便官方排查。Anthropic 兼容接口的错误体里也有 request_id，官方对它的说明就是便于排查问题。
这两个标识只在出错那一刻存在，事后是补不回来的。所以真正该做的动作是在客户端日志里默认落盘：不管成功失败，都把响应头里的 trace_id 记下来；对 Anthropic 兼容链路，把 request_id 和 error.type 一并记进结构化日志。等到你需要找官方时，手里有具体某一次调用的标识，和只能说”我们昨天下午一直报错”，处理速度完全是两码事。
整篇下来，真正需要先落到代码里的判断只有一条：别把 HTTP 200 当成成功。OpenAI 兼容链路的语义是”HTTP 通了”不等于”业务成功”，官方在这份接口文档里只定义了 200 这一档响应，成败要去读 base_resp.status_code。先把这个判断补上，再谈错误码对照表。