前言
本文整理了HTTP 标准状态码 + 国内主流大模型平台专属业务错误码，覆盖 OpenAI 兼容体系、MiniMax、DeepSeek、智谱 GLM、通义千问（阿里百炼）等，同时配套问题排查方向与通用异常处理策略，适用于对接大模型 API 开发、运维、问题排查及接口标准化落地。
一、通用 HTTP 状态码（全平台通用）
HTTP 状态码是所有大模型 API 统一基础错误标识，分为客户端异常(4xx)、服务端异常(5xx) 两大类。
1. 4xx 客户端错误（请求方问题，无需频繁重试）
| HTTP 码 | 错误名称 | 错误说明 | 排查方向 |
|---|---|---|---|
| 400 | Bad Request | 请求格式错误、JSON 解析失败、参数缺失、Prompt 为空、字段类型不合法 | 校验请求体、JSON 格式、必填参数、文本内容 |
| 401 | Unauthorized | 鉴权失败：API Key 不存在、未携带密钥、Token 过期、签名错误 | 核对 API Key、请求头、密钥有效期 |
| 402 | Payment Required | 账户余额不足、套餐已耗尽（预付费平台高频出现） | 查看账户账单、完成充值 |
| 403 | Forbidden | 权限受限：IP 封禁、地域限制、模型未开通使用权限、接口白名单拦截 | 检查IP白名单、账号权限、模型开通状态 |
| 404 | Not Found | 接口地址错误、模型名称不存在、接口已下线 | 核对请求URL、模型名称拼写 |
| 422 | Unprocessable Entity | 参数校验不通过：温度/采样值越界、单轮上下文超长、参数取值非法 | 检查模型参数范围、输入文本长度 |
| 429 | Too Many Requests | 接口限流：RPM（每分钟请求数）、TPM（每分钟Token数）、并发数超限 | 降低调用频率、控制并发、申请提升配额、增加重试机制 |
| 499 | Client Closed Request | 客户端主动断开连接（流式输出场景高发） | 优化客户端超时配置、避免强制中断请求 |
2. 5xx 服务端错误（平台侧问题，可适度重试）
| HTTP 码 | 错误名称 | 错误说明 | 排查方向 |
|---|---|---|---|
| 500 | Internal Server Error | 模型服务内部异常、程序Bug、依赖服务故障 | 短时重试，持续报错联系平台客服 |
| 502 | Bad Gateway | 网关/反向代理异常，上游推理服务无响应 | 间隔重试，属于平台链路问题 |
| 503 | Service Unavailable | 服务过载、平台临时维护、算力资源耗尽 | 停止高频调用，延后重试 |
| 504 | Gateway Timeout | 网关超时，长文本/大模型推理耗时过长 | 缩短输入内容、更换轻量模型、调大客户端超时时间 |
二、主流大模型平台专属业务错误码
在 HTTP 状态码基础上，各平台会返回自定义业务码/错误描述，用于精细化定位问题。
1. OpenAI 及全兼容体系（通用接口标准）
主流开源模型、中转服务均沿用该错误字段：
| 错误字段 | 对应HTTP码 | 含义 |
|---|---|---|
| invalid_request_error | 400 | 请求参数、格式非法 |
| authentication_error | 401 | 密钥鉴权失败 |
| permission_error | 403 | 账号无对应模型/接口权限 |
| rate_limit_error | 429 | 接口触发限流 |
| server_error | 500 | 服务端内部错误 |
| context_length_exceeded | 422 | 上下文长度超出模型上限 |
| model_not_found | 404 | 指定模型不存在 |
2. MiniMax（稀宇科技）
国内主流大模型平台，统一使用数字业务码：
| 业务码 | 含义 | 对应场景 |
|---|---|---|
| 1000 | 未知错误 | 未归类的突发异常 |
| 1001 | 请求超时 | 推理/网络超时 |
| 1002 | RPM 限流 | 每分钟请求数超限 |
| 1004 | 鉴权失败 | API Key / Token 无效 |
| 1008 | 账户余额不足 | 账户欠费、套餐用完 |
| 1026 | 输入内容违规 | Prompt 命中安全风控、敏感内容 |
| 1027 | 输出内容违规 | 模型回复触发安全拦截 |
| 1039 | TPM 限流 | Token 调用量超限 |
3. DeepSeek（深度求索）
以 HTTP 码 + 英文描述为主，无大量自定义数字码：
| 标识 | 对应HTTP码 | 含义 |
|---|---|---|
| Insufficient Balance | 402 | 账户余额不足 |
| model_not_found | 404 | 模型名称错误/未上线 |
| context_length_exceeded | 422 | 上下文超长 |
| 参数非法 | 422 | 自定义字段、参数取值不符合要求 |
4. 智谱 GLM
数字业务码为主，聚焦鉴权场景：
| 业务码 | 含义 |
|---|---|
| 1000 | 认证失败 |
| 1001 | 未携带 Token |
| 1002 | Token 非法 |
| 1003 | Token 已过期 |
5. 通义千问 / 阿里百炼
以英文错误标识为主，侧重参数与安全风控：
| 错误标识 | 含义 |
|---|---|
| InvalidParameter | 参数非法、文本超长、字段错误 |
| FaqRuleBlocked | 内容命中安全规则，被拦截 |
| ServiceUnavailableError | 服务临时不可用、角色配置非法 |
三、场景化快速排查对照表
日常对接可根据现象直接定位根因，提升排错效率：
| 故障现象 | 匹配错误码 | 核心处理方案 |
|---|---|---|
| 密钥登录/调用失败 | 401、1004、1000(智谱) | 核对API Key、请求头、密钥有效期 |
| 调用频繁被拦截 | 429、1002、1039 | 降低QPS、增加间隔、开启退避重试 |
| 无法发起新调用，提示欠费 | 402、1008 | 账户充值、核查账单与套餐 |
| 输入文本直接被拒绝 | 400、1026、FaqRuleBlocked | 过滤敏感内容、精简Prompt |
| 接口长时间转圈、超时断开 | 504、1001 | 缩短输入文本、更换小模型、调大超时时间 |
| 模型无返回、服务报错 | 500、502、503 | 短时重试，持续异常联系平台运维 |
| 填写模型名后调用404 | 404、model_not_found | 核对官方模型名称、接口地址 |
四、通用代码异常处理规范
对接多模型平台时，统一异常处理逻辑，避免服务雪崩：
- 4xx 客户端错误 不重复重试，优先校验请求参数、密钥、内容合规性，直接返回前端/业务层错误提示。
- 429 限流错误 采用指数退避重试（1s → 2s → 4s），限制最大重试次数（建议3次以内），同时全局控制并发量。
- 5xx 服务端错误
有限次数重试（2
3次），重试间隔25秒，多次失败则判定服务不可用，停止调用。 - 内容风控拦截（1026/1027/FaqRuleBlocked） 直接返回合规提示，禁止重试，避免重复触发风控。
- 余额不足(402/1008) 触发告警通知，暂停批量调用，引导账户充值。
五、补充说明
- 国内所有合规大模型均已上线内容安全风控，涉政、违规、敏感内容会触发 1026/1027 类拦截，属于正常安全策略。
- 长上下文、多模态、复杂 Agent 推理场景，更容易出现
504 超时，建议拆分请求、分步调用。 - 不同平台限流规则（RPM/TPM）独立，多模型混用时需分别做流控管理。