故障排查¶

先区分网络失败、鉴权失败、模型/参数错误和额度/容量限制。同一个 HTTP 状态可能对应不同原因，判断时同时看响应体。

获取状态、响应头与错误体¶

在已经设置 ROUTEFAST_API_KEY 的 macOS / Linux / WSL 终端运行：

if [ -z "${ROUTEFAST_API_KEY:-}" ]; then
  printf '请先在当前终端设置 ROUTEFAST_API_KEY。\n'
else
  curl --silent --show-error --include \
    --connect-timeout 10 --max-time 30 \
    https://api.routefast.ai/v1/models \
    -H "Authorization: Bearer $ROUTEFAST_API_KEY"
fi

这里的 10 秒连接超时、30 秒总超时只用于模型列表诊断，不是长文本生成的推荐上限。命令显示响应头和响应体，不打印请求中的 Key；排障时不要开启 shell 的 set -x 或直接共享带凭证的 curl -v 输出。

返回模型列表：本次网络与入口检查已通过，继续检查目标模型和生成请求。
HTTP 401 / 403 / 429：按照下表查看具体错误字段。
DNS、TLS、连接超时：请求可能没有到达网关；记录 curl 错误，不要先改模型或充值。
返回 HTML 而非 API JSON：检查实际访问地址，并保留响应状态和页面错误标题，可能需要排查代理或 CDN。

保存响应头中的 X-Client-Request-ID；如果没有该头，提供时间、时区和客户端本地记录即可。不要把客户端自填 ID 当作服务端已接收的证据。

按错误字段处理¶

入口可能返回 { "code": "...", "message": "..." }，处理器也可能返回 { "error": { "type": "...", "message": "..." } }。不同端点或上游返回的错误外壳可能不同，请同时查看 HTTP 状态、错误字段和消息。

HTTP / 常见字段	先做什么	是否直接重试
`401` `API_KEY_REQUIRED` / `INVALID_API_KEY`	检查 Key、`Bearer`、空格和当前终端变量	否，先修正凭证
`401` `API_KEY_DISABLED` / `USER_INACTIVE`	检查 Key 或账户是否停用	否
`403` `API_KEY_EXPIRED`	检查有效期，更新正在使用的 Key	否
`403` `INSUFFICIENT_BALANCE`	检查账户余额	否，余额恢复后再试
`403` `ACCESS_DENIED`	核对实际出口 IP 与 Key 的 IP 限制	否
`403` `GROUP_DISABLED` / `GROUP_DELETED` / `GROUP_NOT_ALLOWED`，或未分组 `permission_error`	检查所属分组及访问权限	否
`404` `model_not_found`	复制当前 Key 模型列表中的精确模型 ID；仍失败时联系支持	不要反复重放相同请求
`429` `insufficient_quota` / `API_KEY_QUOTA_EXHAUSTED`	检查 Key 总额度，不能只看账户余额	否，先处理额度
`429` `rate_limit_exceeded`	区分费用窗口、用户/分组 RPM 等；看消息及 `Retry-After`	按恢复条件等待
`429` `rate_limit_error`	检查是否并发/排队或上游限流	降低并发，有限退避
`429` `INVALID_AUTH_RATE_LIMITED`	停止持续发送错误 Key 的程序，修正配置后等待	不要继续尝试随机 Key
`403` `billing_error`	查看消息确认余额或其他计费资格原因	不能统一按临时故障重试
`502` `upstream_error`	查看是否上游鉴权或临时服务异常	临时故障可有限重试；持续鉴权故障联系支持
`503` `API_KEY_AUTH_OVERLOADED` / `billing_service_error` / `api_error`	保留请求 ID，稍后再试	有限退避，持续失败联系支持

400 常见于无效 JSON、必填参数缺失、上下文或参数不兼容。不要在没有确认请求体的情况下自动切换模型。部分订阅或平台额度错误仅在相关配置启用时出现，详见额度、并发与限流。

Base URL 与 `404`¶

客户端	正确配置
Claude Code `ANTHROPIC_BASE_URL`	`https://api.routefast.ai`
Codex `model_providers.routefast.base_url`	`https://api.routefast.ai/v1`
OpenAI Python `base_url`	`https://api.routefast.ai/v1`
OpenAI JS `baseURL`	`https://api.routefast.ai/v1`

检查最终请求路径。/v1/v1/responses 表示重复添加 /v1；接入时统一使用上表地址，避免依赖其他路径别名。404 model_not_found 与路径错误不同，应检查模型 ID 和分组。

余额充足但请求仍失败¶

账户余额、Key 总额度、Key 费用窗口、用户并发和 RPM 是不同限制。创建多个 Key 不能保证提高同一个用户的共享限制。

先核对当前 Key 属于正确分组：Claude/Claude Code 使用 Anthropic-Claude，GPT/Codex 使用 OpenAI-ChatGPT。再按实际错误检查额度或限制。已列出模型也可能暂时没有可调度容量，不能只靠反复获取模型列表判断容量恢复。

Claude Code 仍要求登录¶

在启动 claude 的同一个终端中配置：

export ANTHROPIC_BASE_URL="https://api.routefast.ai"
export ANTHROPIC_AUTH_TOKEN="sk-routefast-..."
claude

检查 ~/.claude/settings.json 的 JSON 是否有效、env 是否正确合并，以及是否存在旧的 ANTHROPIC_API_KEY、企业网关或云平台配置。先确认来源，再按Claude Code 教程选择一致的配置方式。

claude --version
claude doctor

在 Claude Code 内执行 /status，核对实际 Anthropic base URL 与凭证来源。父终端变量与 settings.json.env 可能不同，单看 export 的结果不足以判断客户端连接。不要把登录提示一概判断为余额问题；记录完整提示和客户端版本。

Codex 仍连接其他提供商¶

运行 /status，确认 provider 为 routefast，并核对 Codex 配置。在启动 Codex 的同一个终端中只检查变量是否存在：

test -n "${ROUTEFAST_API_KEY:-}" && printf 'key is set\n'
codex --version

如果变量未设置，先补齐环境变量；修改配置后退出再重启客户端。不要打印完整 Key，也不要直接覆盖已有 config.toml。

流式卡住、中断，或 HTTP `200` 但失败¶

流式连接发送过响应头或心跳后，服务端可能无法再修改 HTTP 状态。Responses 路径可能发送 response.failed；Messages 等路径可能发送错误事件。客户端必须检查协议的完成/失败事件，不能只判断状态码。

区分只有心跳、已输出部分文字、明确错误事件、没有终止信号直接断开。
保留错误事件、响应 ID、模型和客户端版本；使用简单、不含私有数据的请求复现。
检查客户端读取超时和自有反向代理的 SSE 缓冲；使用 CLI 时同时记录本地代理是否开启。
在用量页核对原请求，再决定是否重发。中断不代表上游没有处理，也不保证没有费用。

正常完成事件代表协议请求结束，也仍需检查返回状态和业务结果；例如输出达到上限可能表现为未完成或截断。

重试规则¶

Key 无效、过期、分组权限、模型不支持、余额或 Key 总额度耗尽：先修正原因。
RPM、短暂容量或并发限制：降低请求频率，优先遵守实际返回的 Retry-After。
费用窗口耗尽：等待该窗口恢复或处理对应额度，不要每秒重试。
没有恢复提示的临时 502 / 503：使用带抖动的指数退避，并同时限制次数和总等待时间。
检查 SDK 是否已经自动重试，避免外层再次叠加成大量重复请求；涉及写文件或外部工具操作的完整任务更不应盲目重跑。

Retry-After 不保证每类错误都返回。请求 ID 也不是幂等键，不能保证重试只计费一次。

报障模板¶

将以下信息发给 support@routefast.ai：

发生时间与时区：
客户端、版本与操作系统：
端点、模型、是否流式：
HTTP 状态：
错误 code / type 与脱敏消息：
响应头 X-Client-Request-ID（如有）：
问题频率：偶发 / 持续
最小复现步骤：
对应时间的用量记录（如有，先脱敏）：

不要发送完整 API Key、完整 Prompt、私有源码或其他凭证。当前没有响应 ID 或查不到记录时，照样可以提交时间与复现信息；不要假定所有失败请求都会产生可见用量记录。