AI API 返回错误时，如何判断问题出在网络、配额还是模型权限

同样的报错文本可能来自链路、配额或权限。先看连接阶段是否完成，再结合响应来源、错误体和限流信息判断；只有证据指向出口时，才做受控的代理 IP 对照。具体错误码以目标服务文档为准，测试使用自有账号和测试额度。

怎么先判断错误发生在连接阶段还是 API 响应阶段？

先确认请求走到哪一步，再读报错。

• 现象：无法解析域名 ｜ 停在哪一段：DNS ｜ 说明：可能尚未形成到目标 API 的 HTTP 请求；DNS 查询本身可能已发出，或由代理侧完成
• 现象：连接超时或被拒绝 ｜ 停在哪一段：TCP ｜ 说明：代理或目标不可达
• 现象：TLS 握手失败 ｜ 停在哪一段：TLS ｜ 说明：证书、SNI、中间设备
• 现象：收到 4xx/5xx 或 request ID ｜ 停在哪一段：某一层返回了 HTTP 响应 ｜ 说明：核对响应来源、网关日志及服务方 ID 定义，才能判断上游是否处理
• 现象：长时间无响应后断开 ｜ 停在哪一段：传输 ｜ 说明：需看首字节时间

拿到 HTTP 响应只说明某一层返回了响应。应结合响应来源、网关日志、错误体、连接阶段记录及服务方对 request ID 的定义，判断请求是否到达并由上游处理。若目标域名解析失败，可能尚未形成到目标 API 的 HTTP 请求，但 DNS 查询可能已出机或由代理完成。

不同错误码和症状分别该查什么？

先用上一节判断连接是否完成，再用本表核对响应状态和服务方错误定义。

• 症状：429，含 Retry-After 或限流 header ｜ 常见线索 / 需核验的原因：配额、速率或并发限制 ｜ 关键证据：读限流头，再查账户、项目与用量控制台
• 症状：401，提示鉴权失败 ｜ 常见线索 / 需核验的原因：密钥错误、过期或作用域不足 ｜ 关键证据：错误体与密钥配置；换密钥能否恢复取决于服务方
• 症状：403，提示地区或模型不可用 ｜ 常见线索 / 需核验的原因：权限或可用范围 ｜ 关键证据：换出口是否无效、换地区或换模型是否有效
• 症状：404，模型不存在 ｜ 常见线索 / 需核验的原因：模型名称或版本错误 ｜ 关键证据：以服务方模型列表接口与错误体为准
• 症状：5xx，含 request id ｜ 常见线索 / 需核验的原因：上游服务异常或策略拦截 ｜ 关键证据：同一请求在多地一致失败

状态码含义因服务方和网关而异，应以对应文档、错误体及限流头为准；同时核对账户、项目、模型权限和用量。证据仍不足时，记录缺少的对照条件再补测。

连接失败、超时或 TLS 报错时先查什么？

连接超时、重置或 TLS 握手失败时，先根据失败阶段检查代理可达性、目标端口、证书链、SNI 和系统时间。

• 连接超时：先看代理是否可达，再看目标端口是否放行；
• 连接被重置：常见于代理 IP 路径中断或中间设备干预；
• TLS 握手失败：核对证书链、SNI 与系统时间，抓包看握手停在哪一步。

若连接已建立但首字节很慢，归入响应耗时观察：TTFB 同时包含连接路径与上游处理，先记录现象，再结合服务端响应和同条件对照定位。更换出口后的变化只能提示出口或路径相关，不能单独确认原因。

网络故障和产品缺陷难以区分时，可参考多地区测试发现问题，如何判断是网络故障还是产品缺陷？。

收到 429 时，怎么区分配额和限流？

部分短窗口限流会在等待窗口后缓解；余额不足、硬配额耗尽或项目权限问题通常需要相应配置或账务处理，不能假定等待即可恢复。

• 账号或项目级限制候选：同一账号在多个出口重复出现；这不能单独证明账号配额耗尽。
• 出口相关限制候选：固定账号、请求和时间窗口后，多个配对样本随出口变化；恢复也不能单独证明 IP 限流。
• 并发限制候选：低并发与高并发结果不同；还需核对实际并发、限流头和服务端错误体。

更换出口只能作为初筛：它可能同时改变网络路径、IP 和服务端状态。应固定账号、请求、并发和时间窗口做重复对照，并结合错误体、限流头、控制台用量与项目配置判断。换 IP 无效不单独证明账号限额，换 IP 后恢复也不单独证明 IP 限流；证据不足时标记为未确认。并发限制还需记录请求是否同时发出，不能只看总量。

收到 403 或模型不可用提示时怎么排查？

收到 403 或模型不可用提示时，按错误体区分地区范围、模型名称与账号授权，并核对服务方文档和账号配置。错误稳定复现仍只是线索，不能单独证明权限问题；继续换代理也不能替代配置核验。

• 403 且提示地区不支持：核对公布的可用范围；
• 404 且提示模型不存在：核对模型名称、版本与账号可见列表；
• 403 且提示无模型权限：检查账号授权。

需要进一步核对地区功能可用性与权限配置时，可参考SaaS 功能地区可用性提示不准确，如何检查权限与配置？。

怎样记录排查结论，方便后续复现？

为便于复现，按下表记录每次排查使用的条件和结果：

• 字段：时间 ｜ 记录内容：UTC 时间，必要时标注本地时区
• 字段：环境 ｜ 记录内容：服务商与 API、模型、账号（按组织策略脱敏）
• 字段：出口 ｜ 记录内容：地区与脱敏后的出口标识
• 字段：过程 ｜ 记录内容：DNS、TCP、TLS、首字节各阶段耗时
• 字段：响应 ｜ 记录内容：状态码、错误码、request ID（按策略处理）、限流头
• 字段：尝试 ｜ 记录内容：重试次数与每次的结果
• 字段：核对 ｜ 记录内容：账号、配额、模型与地区权限的检查结果
• 字段：结论 ｜ 记录内容：判断与置信度；未确认时写出下一步要补的对照

结论可写成：“服务方返回 429 和 request ID；同账号多出口复测仍复现，暂倾向账号/项目级限制，待控制台用量确认。”若证据不足以区分限流层级，标记为未确认，并注明待补的对照。

HTTP Semantics（RFC 9110）说明 HTTP 响应状态的通用语义；具体 API 错误、限流与 request ID 含义仍应以服务方文档为准。

FAQ

Q：429 一定代表账号配额用尽吗？

A：不一定，也可能是短时限流或并发限制；应结合响应头、错误体和账号控制台判断。

Q：403 一定是模型权限问题吗？

A：不一定，地区限制、组织策略或资源状态也可能导致 403，需以服务方错误说明为准。

Q：没有 request ID 还能提交问题吗？

A：可以提供时间窗口、脱敏请求特征和响应码，并注明服务端未返回 request ID。