错误码总表
HeteroFlow 是本站的异构算力与大模型调度产品。错误码总表。大模型推理接口错误响应统一为 OpenAI 兼容结构，code 为机器可读错误码：按码编写分支逻辑而非解析文案；错误码总表覆盖配额限流、鉴权、渠道与数据等级各类拒绝场景与处置建议。
错误码总表
> 大模型推理接口错误响应统一为 OpenAI 兼容结构，code 为机器可读错误码：按码编写分支逻辑而非解析文案；错误码总表覆盖配额限流、鉴权、渠道与数据等级各类拒绝场景与处置建议。
错误响应结构
推理接口（/v1/*）错误响应统一为：
{
"error": {
"message": "密钥当日调用次数已达上限（1000 次/日）",
"type": "switchyard_error",
"code": "daily_request_limit_exceeded"
}
}管理 / 治理 API 的业务拒绝多为 HTTP 200 + success:false + error_code（如 invalid_parameters），与推理网关层的拒绝（HTTP 4xx/5xx + 上面的 error 结构）是两种形态。
总表
| HTTP | 错误码 | 含义 | 处理建议 |
|---|---|---|---|
| 400 | invalid_request | 请求体不合法（JSON 损坏、缺 model 字段或字段类型错误） | 对照端点总表检查请求体 |
| 400 | model_price_error | 模型未在计费价格表内（多为名称拼写错误或未上架） | 从模型广场复制准确模型名；注意大小写与前缀 |
| 401 | invalid_api_key | 密钥不存在、已删除、已耗尽或已过期 | 检查 Authorization: Bearer sk-… 格式；在「API 密钥」页确认密钥状态 |
| 403 | key_scene_mismatch | 密钥绑定的端点场景与本次调用不符 | 换用未限场景的密钥，或走调整申请放开场景 |
| 403 | data_level_denied | 密钥数据等级超出模型/渠道最高承载等级 | 换承载等级足够的模型（本地部署），或申请对应等级的密钥 |
| 403 | model_role_forbidden | 模型仅对特定角色开放，当前角色不在开放集合 | 联系管理员调整模型开放范围或本人角色 |
| 403 | access_denied | 模型未获本租户授权（租户能力范围外） | 联系管理员为本租户开通该模型 |
| 403 | （无码，文案「该令牌无权访问模型 xxx」） | 密钥的模型白名单不含该模型（分组/白名单限制） | 换密钥，或走调整申请扩大模型范围 |
| 403 | pre_consume_token_quota_failed | 密钥剩余额度不足，预扣费失败 | 充值或换用有余额的密钥 |
| 403 | AUTH_INSUFFICIENT_PRIVILEGE | 管理/治理接口：权限不足 | 由被授权角色的账号执行该操作 |
| 403 | AUTH_TENANT_ADMIN_REQUIRED | 管理/治理接口：要求本租户管理员登录会话 | 用租户管理员账号登录后操作；API 凭据（PAT）不能代行 |
| 404 | invalid_url | 请求路径不存在（/v1 下的未知端点） | 核对端点拼写；对话接口是 /v1/chat/completions |
| 429 | monthly_quota_exceeded | 月度额度（token 量或金额计量）已用尽，本月熔断 | 在额度配置中申请提额，或等待下月额度窗口 |
| 429 | daily_request_limit_exceeded | 当日调用次数超过配置上限 | 等待次日窗口，或申请调大日调用上限 |
| 429 | rate_limit_exceeded | QPS 或并发超过阈值（message 会注明是频率还是并发） | 客户端退避重试（建议指数退避）；压测前联系管理员调阈 |
| 503 | model_not_found | 模型已配置价格但当前无可用渠道（渠道被禁用/移出候选） | 稍后重试；持续出现请联系管理员检查渠道状态 |
| 504 | （上游超时） | 上游服务响应超时 | 减小输入规模或降低并发后重试 |
> 个别旧场景 code 可能为空串，此时以 message 文本判读。
401：密钥与身份问题
1. 密钥本身：确认完整复制（sk- 开头无多余空格）、密钥未被删除/禁用、未设过期时间或已过有效期；
2. 会话吊销：浏览器端登录态突然全部失效（管理台 401），常见原因是管理员重置了权限或身份源停用信号命中——账号被禁用会吊销全部既有会话，需重新登录确认账号状态；
3. PAT / API 凭据：需要登录会话的操作（如租户管理接口）用 PAT 打会得到 AUTH_TENANT_ADMIN_REQUIRED——这不是密钥错误，是身份形态要求。
403：越权问题（先分清是哪一种）
| 场景 | 判别 | 处理 |
|---|---|---|
场景不匹配（key_scene_mismatch） | 密钥绑定了「对话」却去调 /v1/embeddings | 场景与端点对齐，或申请放开场景 |
数据等级（data_level_denied） | 敏感/内部密钥调了云端模型 | 换本地部署承载的模型，或按数据实际等级申请密钥 |
角色未开放（model_role_forbidden） | 模型标注「仅管理员」等开放范围 | 换开放模型，或找管理员调整开放集合 |
租户未授权（access_denied） | 模型不在本租户能力集内 | 管理员为租户开通后再用 |
| 密钥白名单（无码，文案「该令牌无权访问模型 xxx」） | 密钥开了模型白名单但目标模型不在其中 | 换密钥或走调整申请 |
管理接口（AUTH_* 族） | 打的是管理/治理 API | 权限族找被授权角色，身份族用租户管理员登录会话 |
跨租户调用是设计禁止项：A 租户的密钥永远调不到 B 租户的专属渠道/模型，表现为 access_denied——这不是故障。
429：三种「限」的分辨
看 code（必要时看 message）：
1. 日调用（daily_request_limit_exceeded）：当日次数到顶——次日自动重置；短期救急可让管理员调大上限；
2. QPS / 并发（rate_limit_exceeded，message 注明「调用频率」或「并发」）：瞬时压力——客户端加指数退避、压并发池；压测前先报备调阈；
3. 月额度（monthly_quota_exceeded）：本月熔断——只能提额或等下月，重试无意义。
注意：被 429 明确拒绝的请求不消耗日调用计数——不要因为「怕烧配额」而不敢重试；但重试仍应带退避，避免持续撞 QPS。
503：无渠道 vs 上游故障
503 model_not_found：平台侧没有任何可用渠道承载该模型（渠道全被禁用、探测停用或被数据等级过滤光）。特点：请求没有出平台。这类「选路失败」不消耗密钥日限额度——只有真正转发到上游的请求才计数，反复重试不会白烧配额，但也修不了根因，请联系管理员检查渠道；- 502/504 或流中断：请求已到上游、上游故障或超时。这类请求已计数计费（按实际用量），处理方式是降低输入规模/并发后重试，或换模型。
网络类（超时 / 连接拒绝）
1. 确认 Base URL 正确：SDK 场景是 https://api.example.com/v1，cURL 直连是 https://api.example.com/v1/chat/completions；
2. 私有化部署检查反向代理的读超时（流式建议 ≥ 300s）与请求体大小限制；
3. 客户端侧检查出口 IP 是否被白名单（allow_ips）拦截。
FAQ
Q：请求失败会扣额度吗？
明确拒绝（429/403/401）不计数不扣费；选路失败（503 model_not_found）不消耗日限；已转发上游后失败（5xx/超时）按实际用量核算。
Q：流式长请求为什么余额先掉一大块？
预扣机制：流式长请求会预扣额度，结束后按实际用量多退少补，短时间的余额波动属正常。
Q：改了额度配置为什么没生效？
配置在提交后的下一请求生效；若跨实例部署，读取有秒级收敛窗口，稍等后重试。
Q：密钥泄露怎么办？
立即在「API 密钥」页删除该密钥（已删密钥立即 401），再走申请签发新密钥；必要时请管理员核查该密钥近期的调用流水。
Q：为什么浏览器端登录态会突然失效？
会话有轮转与吊销机制：管理员禁用账号、身份源停用信号、安全策略变更都会吊销既有会话；重新登录即可，若登录仍失败说明账号已被停用，需联系管理员。
Q：报障时怎么让管理员快速定位我的请求？
把响应头 X-Oneapi-Request-Id 的编号提供给管理员，可在调用日志中精确定位那一次请求（见快速开始）。