开发者指南 · API 接入与选购

# API 中转报错排查：401、403、404、429 与 503

排查星火AI API 接入中的认证失败、分组权限、地址错误、限流和服务暂不可用，减少无效重试。

星火AI 智能网关 · 更新于 2026-10-09

接入出错时，先记录请求时间、HTTP 状态、模型、接口路径和返回的错误代码。保留请求 ID，但不要公开 Authorization 头或完整密钥。以下是排查方向，最终原因以具体返回信息为准。

## 按状态码定位问题

| 状态 | 优先检查 | 建议动作 |
| --- | --- | --- |
| 401 | 密钥缺失、错误或失效 | 检查 Bearer 认证、复制空格、客户端是否使用了旧密钥 |
| 403 | 分组、模型或策略权限 | 核对该 Key 的分组和可用模型，按响应说明处理 |
| 404 | 端点或模型名 | 检查 /v1 是否重复，确认请求路径与模型 ID |
| 429 | 并发、请求频率或额度限制 | 读取错误说明，降低并发；有 Retry-After 时按其等待 |
| 502 / 503 | 服务暂不可用或网络故障 | 短暂等待、限制重试次数；持续失败时联系本站支持 |

## 看到 SVC_1001 怎么办

这是本站用于提示服务暂不可用的错误代码。它不能单独证明你的密钥余额不足。先查看本站余额与用量，再携带时间、模型和请求 ID 联系支持；不要持续自动提交同一请求。

## 地址错误与模型错误如何区分

使用 `GET /v1/models` 核对密钥能看到的模型；聊天请求使用 `POST /v1/chat/completions`。Claude Code 使用 Messages 配置，见[接入教程](https://ai.wfpromax.xyz/guides/claude-code.html)。如果返回 HTML 而非 JSON，优先检查是否访问了网页路径、登录页或代理错误页。

## 流式输出中途断开

记录已收到的内容、持续时间和客户端超时。中断可能发生在客户端、网络或服务端；仅凭一个错误不能确定原因。先用更短的输入和更小的输出限额复现，再比较非流式请求。不要立刻重复长任务，先核查是否已有用量记录。

## 提交问题前准备哪些信息

- 请求时间与时区、接口路径、HTTP 状态及错误代码。
- 模型 ID、是否流式、客户端名称与版本。
- 脱敏后的最小请求，以及返回的请求 ID（如有）。
- 是否能通过短请求复现；切勿附带真实密钥和无关聊天内容。

首次接入请从[最小请求教程](https://ai.wfpromax.xyz/guides/openai-compatible-api.html)开始。费用疑问请参照[计费核对方法](https://ai.wfpromax.xyz/guides/token-billing.html)。

## 选好模型，把想法接入应用

查看当前模型与账户价格，注册并选择适合的额度，再按指南完成接入。

 [查看模型与价格](https://ai.wfpromax.xyz/available-channels?entry=guide_api-errors) [购买 API 额度](https://ai.wfpromax.xyz/purchase?entry=guide_api-errors) [注册账户 →](https://ai.wfpromax.xyz/register?entry=guide_api-errors)

## 继续阅读

[Claude Code 中转配置：连接星火AI 网关](https://ai.wfpromax.xyz/guides/claude-code.html)[AI API Token 计费说明：输入、输出与缓存](https://ai.wfpromax.xyz/guides/token-billing.html)[星火AI 智能网关是什么：服务、接入方式与适用范围](https://ai.wfpromax.xyz/guides/service.html)[OpenAI 兼容 API 接入教程：Base URL、密钥与模型](https://ai.wfpromax.xyz/guides/openai-compatible-api.html)[AI API 购买与充值指南：模型、价格、额度和兑换码](https://ai.wfpromax.xyz/guides/buying-guide.html)[GPT、Claude、Gemini、Kimi API 怎么选：按任务与成本选模型](https://ai.wfpromax.xyz/guides/model-selection.html)[ChatGPT／Claude 网页会员与 API 额度有什么区别？](https://ai.wfpromax.xyz/guides/api-vs-subscription.html)