跑到一半 USDC 余额不足：API 会返回什么，以及怎么在批处理死一半之前就发现
本文解释使用 USDC 充值的 API key 在余额耗尽时常见的报错形态（如 HTTP 402 支付要求或明确的余额不足提示），并与厂商配额错误（如 429 速率限制、quota exceeded）区分。针对长时间批处理任务，提供开跑前的余额预检方法：查询余额接口、预估 token 用量、设置余额告警，以及设计失败重试和降级逻辑，避免任务中途失败导致资源浪费。
余额耗尽与配额错误：两种不同的失败
在聚合 API 场景下，调用失败可能来自两个层面：聚合站自身的计费余额不足，或上游厂商的配额限制。两者的报错形态不同，处理策略也不同。
- 余额耗尽：通常返回 HTTP 402 Payment Required，响应体中带有明确的余额不足提示，例如“insufficient balance”或“please top up”。这类错误与具体模型无关，任何调用都会失败，直到充值完成。
- 厂商配额错误：常见 HTTP 429 Too Many Requests，响应体可能包含“rate limit exceeded”或“quota exceeded”等字样。这类错误通常与模型、时间段或调用频率有关，换用其他模型或稍后重试可能恢复。
区分二者有助于快速定位问题：402 错误需要检查账户余额，429 错误需要调整请求节奏或查看厂商配额。
长任务开跑前的余额预检
对于需要运行数小时甚至数天的批处理任务，中途因余额不足失败会造成计算资源和时间的浪费。建议在任务启动前执行以下预检步骤。
1. 查询当前余额
调用聚合站提供的余额查询接口（如有），或通过控制台查看可用 USDC 余额。确认余额大于预估消耗。
2. 预估任务消耗
根据任务规模估算 token 用量：统计待处理文本的总字符数，按模型大致换算为 token，乘以单价（官方价 ×1.3）得到预估费用。对于不确定的任务，可先运行小批量样本，测量平均消耗后再放大。
3. 设置余额告警
在账户中设置低余额提醒（如通过邮件或 webhook），确保在余额低于安全阈值时收到通知。安全阈值应覆盖至少一个完整任务周期的消耗。
4. 设计任务级容错
即使预检通过，也建议在代码中实现以下逻辑：
- 捕获 402 错误，立即暂停任务并通知管理员充值，避免无意义重试。
- 捕获 429 错误，采用指数退避重试，并记录错误类型以便区分。
- 将任务分片处理，每完成一片记录进度，便于失败后从断点恢复。
实践建议
- 在批处理脚本启动时调用一次余额查询接口，并与预估消耗比较，低于阈值则拒绝执行。
- 在日志中记录每次调用的错误类型和响应码，便于事后分析失败原因。
- 对于关键任务，可准备备用 API key 或备用充值渠道，但注意聚合站的无 KYC 特性意味着充值到账可能有延迟，需提前规划。
通过上述预检和容错设计，可以显著降低长任务因余额耗尽而中途失败的风险。