API 返回 401、403、429、524,分别该检查什么?
401 通常先查鉴权,403 先查权限或访问策略,429 先查频率、Token 配额或额度,524 则多见于非流式长推理触发 Cloudflare 网关超时。最终要结合响应正文与该站说明判断。
401:Key 是否被正确送达
检查 Key 是否过期、撤销或复制了多余空格,以及 Base URL 是否属于签发它的站点。OpenAI 兼容接口通常使用 Authorization: Bearer;Anthropic Messages 通常使用 x-api-key,还需要相应版本头。
若控制台中 Key 存在但请求仍失败,用临时测试 Key 做最小调用,并确认应用、代理或 SDK 没有覆盖鉴权头。不要把完整 Key 放进问题帖或检测报告。
403:当前请求是否被允许
检查分组模型权限、IP 白名单、地域或组织限制,以及站点的访问策略。如果返回的是 HTML 拦截页,可能是网关或防护层,而非模型接口本身返回的业务错误。
不要持续换地址绕过限制。先向站点确认受支持的接口路径与访问条件,再用同一最小请求复测。
429:区分频率限制与配额不足
查看错误正文中的类型与提示,区分每分钟请求数、Token 用量限制、并发限制和账户额度。一些服务把余额不足也包装成 429;这类问题仅靠重试不会恢复。
若响应提供 Retry-After,按其提示等待;否则减少并发,采用有上限的指数退避并加入随机抖动。记录失败次数,避免失败请求形成重试风暴。
排查记录(示例)
时间:2026-10-27 10:00 +08:00
站点 / 分组 / 模型:api.example.com / A / MODEL_ID
HTTP:429;error.type:rate_limit;Retry-After:30
动作:暂停并发,等待后仅重试一次最小请求。
524 与其他网关错误
HTTP 524 常见于套了 Cloudflare CDN 的中转站:当推理模型思考超过 100 秒且未开启 stream: true 流式返回时,网关会主动断开。启用 SSE 流式输出通常可彻底解决该问题。
修正配置后先做单次复测,再恢复定时监测。短时错误并不直接证明站点长期不稳定;把时间、分组、模型和样本数与状态一起查看。