一句话结论
先查控制台日志，再判断是鉴权、权限、路径、额度或并发、网关连接、上游服务还是请求超时；不要只看状态码猜原因。
适用场景
- 调用接口时看到一串数字错误
- Agent 跑一半突然报错
- 想判断问题位于工具配置、账号分组、网关还是上游模型
常见现象
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 429 Too Many Requests
- 503 Service Unavailable
- 522 Connection timed out
- 524 A timeout occurred
原因解释
- 401：常见于 Key 无效、权限不足、Base URL 与 Key 不配套或认证头未发送
- 403：常见于 Key 分组、模型或接口权限不足，也可能是账号或安全策略拒绝请求
- 404：常见于 Base URL、协议或 endpoint 拼错，也可能是模型名或路由不存在
- 429：常见于请求频率、并发或配额限制，也可能来自上游限流
- 503：常见于网关或上游模型暂时不可用、拥堵或维护
- 522：网关在规定时间内无法与上游建立连接，常见于上游节点、线路或短时连接异常
- 524：表示链路在规定时间内没有得到响应，可能与任务长度、模型速度或网关超时边界有关
解决步骤
- 记录失败时间、工具、模型和请求 ID，到 1A1API 控制台先查对应日志。
- 401：核对 Key 状态、所属分组、Base URL 和认证字段；不要反复重试同一错误配置。
- 403：检查 Key 分组是否允许当前模型和接口；不要用重新粘贴同一 Key 代替权限检查。
- 404：按工具核对协议、Base URL、请求路径和模型 ID；不要给 Codex、Claude Code 和 OpenAI SDK 套同一个通用 `/v1` 规则。
- 429：把并发降到 1，查看分组额度与限流信息，再按响应提示退避重试。
- 503：先用同一 Key 测另一个可用模型；只有个别模型失败时优先判断为模型或上游问题。
- 522：保留失败时间和请求 ID，按对应工具的 Help 页面核对入口；短时异常可限次退避重试或对比另一个当前可用模型。
- 524：缩短输入、减少输出目标或拆分任务，再用同一配置复测。
- 按工具查看当前说明：Codex https://help.1a1api.top/codex；Claude Code https://help.1a1api.top/claude-code；其他客户端从 https://help.1a1api.top/ 进入。
可复制命令
# OpenAI 兼容入口的模型列表测试；不要把真实 Key 写进命令正文或截图
curl -i https://1a1api.top/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
仍然不行怎么办
- 持续 503 / 522 / 524：保留请求 ID 和失败时间，查看 https://help.1a1api.top/troubleshooting 后再决定是否换模型或联系支持。
- 持续 401 / 403：确认地址和分组无误后，再创建一个小额度测试 Key；旧 Key 如疑似泄露应立即停用。
- 持续 404：从对应工具的 Help 教程重新复制 Base URL 和配置字段，不要自行给所有客户端补 `/v1`。
小白先准备什么
- 确认自己用的是哪个平台的 Key（OpenAI / 1A1API / Claude）
- 准备好能跑 curl 的终端（Mac 自带，Windows 用 Git Bash 或 PowerShell）
- 保存状态码、错误 message、请求 ID 和失败时间；分享前删除 Authorization、Cookie、API Key、Token、密码和环境变量值。
- 确认账户余额和 Key 状态（是否被禁用）
验收标准
- 能从控制台日志找到对应请求，而不是只根据状态码猜测
- 401 → 能检查 Key、地址、认证字段和分组权限
- 403 → 能检查 Key 分组、模型和接口权限
- 404 → 能按工具核对协议、Base URL、endpoint 和模型 ID
- 429 → 能把并发降到 1，并按响应或控制台信息处理
- 503 → 能用同一 Key 对比另一个可用模型
- 522 → 能用日志判断网关到上游的连接问题，并限制重试
- 524 → 能拆短任务并记录复测结果
可复制排查提示词
遇到 API 报错时，只分享严格脱敏后的片段；任何密钥或会话凭证都不应发给 AI 或排错群：
我调用模型 API 时遇到报错。以下内容已删除 Authorization、Cookie、API Key、Token、密码和环境变量值：
- 工具：<Codex / Claude Code / OpenAI SDK / 其他>
- 失败时间：<时间和时区>
- 状态码：<401/403/404/429/503/522/524/其他>
- 请求 ID：<如有>
- Base URL：<只写地址，不带密钥>
- 模型：<模型 ID>
- 并发数：<同时几个请求>
- 错误片段：<只贴必要的 message>
请按“工具配置与协议 → Key 与分组 → 网关 → 上游模型”的顺序给出检查项，并说明每一步如何验证。不要要求我提供任何真实密钥或会话凭证。
常见误区
- 误区：429 一定是被封或只需等几秒 → 还要检查额度、并发、请求频率和上游限流信息。
- 误区：403 和 401 一样只要换 Key → 403 更应检查分组、模型和接口权限。
- 误区：404 一定是服务不存在 → 还可能是协议、Base URL、endpoint 或模型 ID 不匹配。
- 误区：503 一定与配置无关 → 它通常指向网关或上游不可用，但仍应通过日志和对比请求确认。
- 误区：所有错误都立即重试 → 401 应先修配置，429 应退避，503 / 524 应限制重试次数。
- 误区：522 和 524 完全一样 → 522 更偏向网关到上游连接阶段，524 更偏向连接后等待响应超时。
- 误区：524 一定是本地网络问题 → 它表示链路超时，需结合任务长度、模型耗时和网关日志判断。
还卡着？
仅把删除凭证、客户数据和环境变量值后的必要截图、日志片段、需求说明或当前页面链接发到 zhemuy@gmail.com。