预付费 API 返回 HTTP 402 之后的几项核对

一次请求返回 HTTP 402，先不要把它当成模型故障。在预付费 API 中，这通常指向支付或可用额度问题，但状态码本身不能说明全部原因。应把响应正文、账户余额和请求记录放在一起看。这篇笔记将几组容易混淆的情况并排记录，方便决定下一步。

§ 余额不足，与密钥不可用

• 余额或支付条件不满足：HTTP 402 的含义是需要支付。在预付费服务中，余额不足是首先值得核对的方向；具体原因仍以服务端错误信息为准，不要仅凭状态码断言充值尚未到账。
• 鉴权或权限问题：HTTP 401 通常与身份凭证有关，HTTP 403 通常表示访问被拒绝。此时应检查密钥、权限和账户状态，而不是直接充值。

在 Vana API 上排查时，先确认当前客户端使用的密钥属于哪个账户，再核对该账户的余额与响应内容。给另一个账户充值，不能据此判断当前请求已经具备支付条件。

§ 补充余额，与减少后续消耗

• 补充余额：适合继续执行原有工作负载。付款完成后，仍应确认余额已经更新，再发起一次小请求验证；支付成功页面不等于原先失败的任务已自动恢复。
• 减少消耗：适合调整之后的预算。缩短上下文、限制输出长度、减少无效循环，都可能降低令牌用量，但不能保证账户在余额不足时仍可调用。

Vana API 按实际令牌用量计费，没有月费。因此，预算检查应关注实际调用，而不只是是否订阅了某个套餐。更换模型前，也应核对当前价格与任务要求，不能只凭名称判断成本。

§ 立即重试，与等待条件改变

• 立即重试：适用于部分短暂网络故障，或服务明确建议重试的情况。对于尚未解决的支付问题，连续重试通常不会改变结果，反而会制造重复日志和告警。
• 暂停并恢复：收到 HTTP 402 后，暂停相关队列，保存任务状态，通知账户负责人。余额或支付条件确认恢复后，再进行有限次数的验证与重放。

不要把所有非成功响应都交给同一套退避逻辑。HTTP 429 通常需要检查限流与调用节奏；HTTP 5xx 更偏向服务端异常。HTTP 402 则应单独进入支付或额度排查流程，最终处理仍需结合响应正文。

§ 接口兼容，与客户端提示一致

• 接口层：Vana API 提供 OpenAI 兼容入口，也支持 Anthropic Messages 与 Gemini 原生协议。排查时，应记录实际使用的协议、请求时间、状态码和服务返回的请求标识。
• 客户端层：Claude Code、Codex、Gemini CLI 或 SDK 可能用不同措辞展示错误。有的只显示摘要，有的保留响应正文；不能只根据界面上的“请求失败”判断原因。

优先查看客户端能够提供的原始错误信息。分享日志前，删除密钥、授权头和敏感输入。若响应无法解释账户状态，可携带脱敏后的请求标识与时间联系支持，而不是反复更换密钥试错。

§ 恢复调用，与重放整个任务

• 恢复调用：先用短输入和较小输出上限验证通路，再逐步恢复并发。一次成功只说明这次调用通过，不代表积压任务都在预算以内。
• 重放任务：确认原任务停在哪一步，检查是否已执行写文件、发消息或修改外部系统等操作。支付恢复不会自动消除重复执行风险，也不要默认接口具备幂等保障。

如果准备使用 Vana API，可以创建账户，先以少量请求验证计费与错误处理。日常运行时，则把余额提醒、消耗记录和 HTTP 402 暂停策略放在同一条运维路径上：先确认原因，再改变条件，最后恢复任务。