按量计费 API 的 402 与 403：六步定位与恢复

一次模型调用失败，先充值还是先查权限？在 CodeRelay Hub 这类按量计费、统一接入多个模型的 API 网关中，建议把“请求能否付款”和“调用者是否获准访问”分开诊断。下面按六步排查，不把状态码直接当成故障结论，也不把换模型当成通用修复。

1. 先确认状态码能说明什么

402 不等于已经确认余额不足。RFC 9110 将它保留供未来使用，没有规定统一的余额、充值或额度语义。因此，只有平台文档和实际响应明确说明计费条件不满足时，才能进入对应的计费排查流程。([rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9110.html?utm_source=openai))

403 表示服务器理解请求，但拒绝执行。凭证有效却不足以获得访问权限，是标准描述的使用场景之一；不过，403 本身不能证明具体是哪条策略拒绝了请求，也不能证明请求已经通过全部身份校验。([datatracker.ietf.org](https://datatracker.ietf.org/doc/html/rfc9110?utm_source=openai))

2. 保留一次失败请求的证据

先暂停这条任务的自动重试，再保存经过脱敏的诊断记录。建议包含请求时间、请求方法、目标路径、模型标识、状态码、响应正文，以及响应中实际提供的请求标识。不要记录完整密钥、完整提示词或用户敏感内容。

• 确认请求来自哪个工作区、项目和运行环境。
• 保留响应中的错误类型与错误说明，不只截取最后一行异常。
• 如果响应不是预期的结构化数据，也保留内容类型和脱敏摘要，避免遗漏中间代理返回的拒绝信息。

如果错误来自 Claude Code、Codex 或 Gemini CLI，建议同时核对客户端实际使用的配置，而不是仅凭终端所在目录判断密钥来源。

3. 遇到 402，逐项核验计费条件

当响应明确指向付款或额度问题时，先核对密钥所属账户，再检查该账户的可用余额、支付状态和已配置的预算限制。把这些项目作为检查清单，不要假设平台一定提供其中所有功能。

接着核对本次请求的输出上限和其他计费相关参数。如果平台存在预授权或额度预留机制，请按它的文档检查；不要自行假定“余额大于零就一定足够”。如果刚刚充值，建议先确认款项进入目标账户，再用一条规模受控的请求验证恢复情况。

不要用自动充值掩盖未知原因。在错误含义尚未确认前，先核清账户与限制，再决定是否调整预算；也不要把降低请求规模视为规避既定预算的办法。

4. 遇到 403，沿权限边界检查

建议按照“密钥归属、项目授权、模型访问、网络策略”的顺序核查，并以平台实际支持的控制项为准。例如，请求 Gemini 2.5 Flash 时，可以检查当前项目是否被允许访问该模型，而不是立即切换到另一个模型碰运气。

同时建议检查部署环境中的密钥是否过期配置、是否误用了另一个工作区的凭证，以及最近是否调整过访问策略。这里的“检查密钥”是核对身份与归属，不是认定每个 403 都能通过更换密钥解决。

如果无法确认拒绝原因，把脱敏响应和请求标识交给管理员或支持人员，并明确询问拒绝发生在哪个权限边界。不要为了让请求通过而扩大全部权限或关闭访问控制。

5. 把恢复动作写进客户端分支

建议在应用内部区分“需要处理计费”“需要处理授权”和“原因尚未确认”三类状态。这些是你自己的诊断分类，不是平台已经承诺的错误字段；映射时应同时检查状态码与文档定义的响应内容。

对于 403，RFC 9110 明确指出，客户端不应使用相同凭证自动重复请求。对于语义依赖平台约定的 402，也建议等待相关计费条件得到确认和修复后，再进行受控验证，而不是直接套用网络故障的重试循环。([rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9110.html?utm_source=openai))

建议把自动模型降级设为独立、显式授权的策略。遇到拒绝时，不要让降级逻辑悄悄改变数据处理路径、预算范围或访问边界。

6. 用最小验证完成闭环

修复后，建议先在原工作区、原权限边界内发送一条最小请求，再恢复队列。每次只改变一个相关条件，记录变更前后的响应，避免同时换密钥、充值和换模型，最后无法判断哪个动作真正有效。

建议为这些场景补充客户端测试：明确的计费拒绝、明确的授权拒绝、缺少错误详情，以及修复后的成功响应。验收重点不是“最终没有报错”，而是失败时能停止无效调用、提示正确处理方向，并留下足够的脱敏证据。

打开 CodeRelay Hub，创建免费工作区。