先看这里：收到错误码不用慌，大部分错误都能通过简单重试或调整解决。本文档按问题端分类：4xx 开头多发生在客户端（请求格式、鉴权、参数等），5xx 开头多发生在服务端（网关、模型原厂模型、网络链路等）。每个错误码下都附有处理建议，遇到无法解决的情况请随时联系技术支持
一、错误码速查表#
| 状态码 | 名称 | 简洁说明 | 问题端 | 处理建议 |
|---|
| 400 | Bad Request | 请求参数格式不对、缺必填字段 | 客户端 | 核对参数 |
| 401 | Unauthorized | API Key无效/缺失/格式错 | 客户端 | 核对鉴权 |
| 403 | Forbidden | 余额不足/无权访问该模型 | 客户端 | 充值 / 核对权限 |
| 404 | Not Found | 接口路径或模型名不存在 | 客户端 | 核对配置 |
| 413 | Payload Too Large | 请求体超出大小限制 | 客户端 | 缩减请求 |
| 429 | Too Many Requests | 触发限流（ RPM / TPM / 并发） | 客户端 | 调整频率 |
| 500 | Internal Server Error | 网关及模型原厂链路异常 | 服务端 | 联系支持 |
| 502 | Bad Gateway | 模型原厂返回了无效响应 | 服务端 | 联系支持 |
| 503 | Service Unavailable | 服务暂时不可用（维护 / 过载） | 服务端 | 稍后重试 |
| 504 | Gateway Timeout | 网关等待模型原厂响应超时 | 服务端 | 重试/联系支持 |
| 524 | A Timeout Occurred | CDN层超时 | 服务端 | 重试/联系支持 |
“问题端 ”表示常见关联环节，不代表最终责任已经确定。具体原因以技术支持结合日志确认结果为准。
二、错误码详细说明#
400（Bad Request 请求格式错误)#
请求体不符合接口规范。网关或模型原厂模型在解析你的请求时就发现格式有问题，通常在进入实际推理前，就被网关或模型原厂的参数校验拦截。缺少必填字段（如 model、messages）
字段类型错误（如 temperature 传成了字符串）
JSON 格式不合法（多余逗号、引号未闭合）
上传文件时 multipart 边界缺失或 body 被截断
模型原厂的模型厂商直接拒绝了请求（如内容审核、区域限制）
401(Unauthorized 鉴权失败）#
网关无法识别你的身份。最常见的错误码之一，通常和 API Key 有关。API Key 缺失（请求头没带 Authorization: Bearer sk-xxx）
API Key 拼写错误、多余空格、复制不全
API Key 已过期或被禁用
请求头格式不对（如把 Key 放进了 api-key 而非 Authorization，取决于网关要求）
403（Forbidden 余额不足 / 无访问权限）#
请求已通过网关的基础鉴权，但由于账户状态、余额、模型权限或模型原厂访问策略等原因，请求被拒绝。403 在本网关下通常对应两类原因：账 户余额不足或无权访问该资源。和 401 的区别：401 是"不知道你是谁"，403 是"知道你是谁，但你被拦下了"。账户余额为 0 或低于单次请求预估费用（网关在转发前会做预算校验，余额不足直接拦截）
额度已用完
当前 Key 未开通该模型的访问权限
请求的模型已下线或处于灰度阶段
404（Not Found 接口/模型不存在）#
请求的路径或模型名在网关/模型原厂找不到。通常是配置或拼写问题。模型名拼错（如 gpt-4o 写成 gpt4o、大小写错误）
使用了网关未映射的模型
接口路径错误（如把 /v1/chat/completions 写成 /v1/chat/completion）
Base URL 拼接多了或少了路径段
413（Payload Too Large 请求体过大）#
请求体超过了网关或反向代理设置的大小上限。常见于上传图片、文件、超长上下文场景。图片/文件 base64 编码后体积膨胀约 33%
历史对话过长导致整体 body 超限
反向代理或网关配置的请求体大小限制，具体阈值以实际配置为准。
429（Too Many Requests 请求限流)#
短时间内请求过多，触发了限流策略。常见限流维度包括 RPM、TPM 和并发数，具体以网关配置为准。RPM（Requests Per Minute）：每分钟请求数
TPM（Tokens Per Minute）：每分钟 token 总量
并发数：同时在处理中的请求数
500(Internal Server Error 网关内部错误）#
在 AI 网关场景下，500 不一定代表模型原厂返回了 500。网关可能会将连接超时、读取超时、TLS 失败、连接被重置，以及将模型原厂返回的 500 等多种服务端异常统一包装为 500。
可能的根因：模型原厂服务暂时不可用或网络抖动
网关到模型原厂服务的连接或等待超时（部分网关默认约为 60 秒，具体以实际配置为准）
TLS 握手失败（证书问题）
模型原厂确实返回了 500（内部错误）
502（Bad Gateway 网关错误响应）#
网关成功连上了模型原厂，但模型原厂返回的响应格式不合法或无法解析。通常与模型原厂响应或服务端链路有关。模型原厂服务重启 / 崩溃中断了响应
模型原厂返回了非标准格式的错误（网关无法解析）
模型原厂中间代理层（如负载均衡）异常
503（Service Unavailable 服务不可用）#
服务暂时无法处理请求。服务暂时无法处理请求，常见原因包括网关或模型原厂服务过载、维护、熔断或区域性故障，属于可恢复的临时状态。模型原厂模型的推理资源满载（高峰期常见）
计划内维护
模型原厂区域级故障
504（Gateway Timeout 网关超时）#
网关把请求转发给了模型原厂，但在限定时间内（通常 60 秒）没有收到模型原厂的响应。请求可能还在模型原厂处理中，也可能已经丢失。模型原厂推理耗时过长（长文本、复杂任务）
模型原厂排队等待（高峰期）
网关侧超时阈值设置过低
524（A Timeout Occurred CDN 层超时)#
524 是 Cloudflare 常见的超时错误码。其他 CDN 可能使用不同的状态码表示类似问题。CDN 在规定时间内没有收到源站（网关）的响应，就可能返回 524。以 Cloudflare 为例，默认通常约为 120 秒，具体以实际 CDN 配置为准。本质是 CDN 和源站之间的超时，不是你的请求有问题。服务端处理耗时超过 CDN 的等待时限
网关到模型原厂链路慢，叠加后超过 CDN 超时
常见于图片生成、视频生成、超长文本推理等慢任务
三、问题处理流程#
收到错误后，可按以下顺序初步判断，便于向技术支持提供有效信息、加快处理速度：1.看状态码首位 4xx 开头多与请求本身相关（格式、鉴权、参数）；5xx 开头多与服务端相关（网关、模型原厂、网络）。2.看 error.type 字段：含 invalid_request_error 多为参数问题；rate_limit_error 是限流；server_error / upstream_error 是服务端问题。3.换个模型试试：同一请求换个模型能通，说明是特定模型的问题（下线/过载/权限）；都不通则是网关或网络层问题。4.记录请求要素：联 系技术支持时提供：请求时间 + 用户名 + 调用模型名 + 完整错误响应 + Request ID（如有），能大幅加快处理速度。
