MiniMax API 的报错大致分四层：HTTP 状态码、响应体里的业务码、传输层超时、上游服务异常。排查时先分层，再定位，不要一上来就改提示词或换模型。很多“模型不行”的问题，最后查出来是 Key 配错、地址混用或超时太短。
本文按 401、403、404、429、5xx 和超时拆开，给出原因、排查顺序和可复用的错误处理代码。模型名、价格和配额以官方文档及站内模型价格为准。
说明：MiniMax 是其权利人的商标。错误码、限流档位和接口行为可能随版本调整，本文以 2026 年 10 月的常见情况为例，最终以 MiniMax 官方文档为准。
一、先分层：状态码、业务码、超时
MiniMax 的官方错误码文档单独列出业务码，并提示反馈问题时提供响应头里的 trace_id。限流文档则按 RPM、TPM 和并发任务数三个维度限制。排查时 HTTP 层和业务层都要看：部分原生接口可能返回 HTTP 200，错误却放在响应体的 base_resp 里；OpenAI 兼容入口通常用 HTTP 状态码表达错误。两层都记录，才不会漏判。
| 现象 | 常见含义 | 优先检查 | 处理 |
|---|---|---|---|
| 401、1004、2049 | 鉴权失败或 Key 无效 | Key、Bearer 请求头、地址是否匹配 | 换新 Key 做最小请求 |
| 403 | 权限、账户状态或入口限制 | 模型权限、实名状态、网关侧额度 | 对照控制台和响应体 |
| 404 | 路径或模型不存在 | Base URL、/v1、模型是否下线 |
查官方模型列表 |
| 400、2013、1039 | 参数错误或 Token 超限 | thinking、temperature、max_tokens | 按文档收紧参数 |
| 429、1002、2045、1041、2056 | 限流、并发或套餐窗口受限 | RPM、TPM、共享 Key、流量脉冲 | 退避、排队、拆 Key |
| 1008 | 余额不足 | 账户余额、订阅额度 | 充值或换计费方式 |
| 超时、1001 | 连接或读取超时 | 网络、代理、长输出、流式设置 | 分层设置超时 |
| 5xx、1024、1033 | 上游服务异常 | 服务状态、请求是否可重试 | 有上限地退避重试 |
日志里至少记录时间、状态码、业务码、模型名、耗时和 trace_id。不要记录完整 Key，也不要把用户原文整段打印到日志。
二、401 与 403：先修鉴权，再查权限
401 表示身份没有通过验证，和模型能力通常无关。按下面顺序排查：
- 请求头是否为
Authorization: Bearer <key>，而不是自定义鉴权方式。 - Key 前后是否有空格、换行或引号，从聊天窗口复制最容易带进来。
- 环境变量是否真的加载，可以只打印前缀确认。
- Key 是否被删除、轮换或停用。
- Base URL 和 Key 是否属于同一平台，官方 Key 配网关地址会 401。
- 反向代理是否覆盖或丢弃了
Authorization头。 - 是否把 M Plan 订阅 Key 和按量计费 Key 混用。官方文档说明两者相互独立，额度不能互当。
403 更多指向权限或账户状态：模型是否开通、账户认证状态、当前入口是否允许该模型、网关侧额度或风控。403 的语义在不同入口可能不同，先看响应体里的错误消息和来源标记。同一请求官方入口正常、网关入口 403 时，先查网关配置和额度。
三、404：Base URL 和模型名最容易错
404 通常不是“接口挂了”，而是请求打到了不存在的路径或模型。常见原因：
- Base URL 写成了别的厂商地址，或者多写、少写了
/v1。 - SDK 会自动拼接
/chat/completions，手写路径时又拼了一次。 - 模型名使用了已下线的旧版本，或大小写、后缀不一致。
- 官方地址和网关地址混用，路径规则不同。
- 反向代理重写规则把路径改坏。
MiniMax 官方模型列表显示，M2.5/M2.7 等历史文本模型已进入下线流程：新用户自 2026 年 10 月 19 日起停止服务，计划 2026 年 11 月 18 日完全下线。当前文档列出的文本模型是 MiniMax-M3 和 MiniMax-M3.1-Flash。继续使用旧模型名，可能得到 404 或业务错误。迁移前先在官方模型列表和站内价格页核对模型名。
四、429：限流不是余额不足
429 表示请求超过了速率、并发或配额限制。MiniMax 官方限流文档按 RPM（每分钟请求数）、TPM（每分钟输入加输出 Token）和并发任务数限制，主账号与子账号共同占用。文档当前列出的 M3/M3.1-Flash 默认档位为：免费用户 20 RPM、充值用户 200 RPM，TPM 分别为 100 万和 1000 万；具体以控制台为准。
常见触发场景：
- 多个服务共用一把 Key，互相挤占额度。
- 批量任务在整点同时启动，形成流量脉冲。
- 重试没有退避，越失败越发，形成重试风暴。
- 长输出或推理任务占用资源，压缩并发空间。
- 套餐窗口到期，触发 M Plan 的资源限制。
对应处理：按项目拆 Key；把批量任务放进队列平滑发送；给重试加上限、指数退避和随机抖动；长输出任务单独限流；如果响应带 Retry-After，优先遵守。收到 429 时不要继续加并发，先把请求压平。
五、超时与 5xx：分清连接、首 Token 和读取
超时不等于服务不可用，要先定位卡在哪一段：
- 连接超时：DNS、网络出口、代理不可达，检查网络和代理。
- 首 Token 很慢：上游排队、提示词过长，缩短输入、错峰或换轻量模型。
- 读取超时：输出太长、推理模型思考久，提高读取超时并限制输出。
- 流式中断：网络抖动、代理断流，客户端要支持重连和去重。
- 异步任务超时：视频、语音任务要区分“任务排队”和“请求超时”，按
task_id轮询，不要重复提交。
5xx 和业务码 1000、1024、1033 通常指向上游异常或过载。这类错误适合退避重试，但要有上限。有副作用的业务先用幂等键或状态查询确认是否执行过。异步语音的下载链接有有效期（官方当前说明为 9 小时），过期需重新获取。
六、错误处理代码：退避、trace_id 和日志
import logging
import os
import random
import time
import httpx
from openai import (
APITimeoutError,
APIStatusError,
AuthenticationError,
OpenAI,
RateLimitError,
)
log = logging.getLogger("minimax")
client = OpenAI(
api_key=os.environ["MINIMAX_API_KEY"],
base_url=os.environ.get("MINIMAX_BASE_URL", "https://api.minimax.cn/v1"),
timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
max_retries=0, # 关闭 SDK 自动重试，统一由下面的逻辑控制
)
def trace_id(exc: Exception) -> str:
response = getattr(exc, "response", None)
headers = getattr(response, "headers", {}) or {}
return headers.get("trace_id") or headers.get("x-request-id") or "-"
def ask(prompt: str, retries: int = 4) -> str:
for attempt in range(retries):
try:
resp = client.chat.completions.create(
model=os.environ["MINIMAX_MODEL"],
messages=[{"role": "user", "content": prompt}],
max_tokens=1024,
)
return resp.choices[0].message.content or ""
except AuthenticationError as exc:
log.error("鉴权失败 status=%s trace_id=%s", exc.status_code, trace_id(exc))
raise
except RateLimitError as exc:
wait = min(2 ** attempt, 30) + random.uniform(0, 1)
log.warning("触发限流 attempt=%s wait=%.1fs trace_id=%s",
attempt + 1, wait, trace_id(exc))
time.sleep(wait)
except APITimeoutError as exc:
wait = min(2 ** attempt, 15) + random.uniform(0, 1)
log.warning("请求超时 attempt=%s wait=%.1fs trace_id=%s",
attempt + 1, wait, trace_id(exc))
time.sleep(wait)
except APIStatusError as exc:
if exc.status_code >= 500:
wait = min(2 ** attempt, 30) + random.uniform(0, 1)
log.warning("上游错误 status=%s attempt=%s wait=%.1fs trace_id=%s",
exc.status_code, attempt + 1, wait, trace_id(exc))
time.sleep(wait)
continue
log.error("客户端错误 status=%s detail=%s trace_id=%s",
exc.status_code, exc, trace_id(exc))
raise
raise RuntimeError("重试次数已用完，请带 trace_id 联系服务方")
print(ask("用一句话解释什么是 API 限流"))
这段代码做了四件事：区分可重试和不可重试错误、指数退避加抖动、把 trace_id 写进日志、对 5xx 单独处理。它不替代幂等设计，有副作用的请求仍要先查状态。
七、日志与监控：最少记哪些字段
- 时间与项目：定位高峰和影响范围。
- HTTP 状态码与业务码：区分鉴权、限流、参数和上游错误。
trace_id或x-request-id：找服务方排查的关键凭证。- 接口地址与模型名：判断是否换模型或换入口后出现。
- 输入输出 Token：分析成本和长请求。
- 耗时、重试次数与并发数：发现尾延迟和重试风暴。
- Key 别名：按项目统计，不要记录 Key 明文。
监控至少按小时统计 401、403、404、429、超时和 5xx 的数量。错误率突增时，先看是否集中在某个项目、某把 Key 或某个模型，再决定降并发、切通道还是回滚版本。
八、联系支持前的检查清单
- 发生时间、时区、持续多久、影响哪些接口。
- HTTP 状态码、业务码和完整错误消息，敏感内容先脱敏。
- 响应头里的
trace_id，以及网关可能附加的x-request-id。 - 接口地址、模型名、SDK 版本和请求参数。
- 一条可复现的最小 curl，去掉业务数据和用户隐私。
- 是官方直连还是网关入口，使用的是按量 Key 还是 M Plan Key。
- 同期并发、RPM/TPM、重试次数和是否有流量脉冲。
- 最近是否换过模型、升级过 SDK、改过代理或网关配置。
- 如果是 1008，附上余额或套餐状态截图，同样先脱敏。
把这些整理成一条消息，比只发“报错了”能快很多。服务方通常第一眼就要 trace_id 和时间窗口。
常见问题
429 是余额不足吗？
不是。429 表示请求超过了速率、并发或配额限制，余额不足对应的常见业务码是 1008。先查并发、共享 Key 和流量脉冲。
为什么 HTTP 200 也会报错？
部分 MiniMax 原生接口用响应体里的 base_resp.status_code 表达业务错误，HTTP 层仍是 200。使用这类接口时，代码不能只看 HTTP 状态，还要解析响应体；OpenAI 兼容入口通常直接返回 HTTP 错误码。
trace_id 在哪里拿？
官方错误码文档提示从响应头读取 trace_id。走网关时，网关可能额外返回 x-request-id，两个都记录。
超时能不能无限重试？
不要。重试要有上限、退避和告警，超时还可能意味着请求已经在上游执行。有副作用的业务先确认状态，再决定是否重发。
换模型后出现 404 怎么办？
先查模型名是否已下线，再查 Base URL 是否多写或少写 /v1。MiniMax 的历史文本模型正在分批下线，旧模型名不能继续假设可用；以官方模型列表和站内价格页为准。
下一步
先在中商起航 AI 网关创建测试 Key，把 401、404、429 和超时各演练一次，再接入生产监控。模型可用性与价格以模型价格为准。
相关阅读：
