Venice 错误与重试手册

要解决的问题

调用 Venice API 时，同一个 HTTP 状态码可能对应完全不同的错误体结构。一个 400 可能只是简单的 StandardError 消息，也可能携带一棵 Zod 校验树；一个 422 在音频生成端点会返回 suggested_prompt，在图像或视频端点却只有一句 "Content policy violation"。如果把所有 4xx/5xx 都当作「失败就重试」，你会在输入格式错误时白白浪费请求配额，在权限不足时反复撞墙，在内容策略拦截后继续发送同样的 prompt。这个技能的作用，是把「收到什么形状的错误 → 该做什么动作」的决策逻辑整理成可执行的参考。

核心能力

四种错误体结构识别。 Venice 所有端点只返回四种错误形状：StandardError（简单的 message 字段）、DetailedError（Zod format() 树加扁平 issues 数组）、ContentViolationError（可能附带 suggested_prompt）、X402InferencePaymentRequired（区分于普通 402，通过 code: "PAYMENT_REQUIRED" 判别）。其中 DetailedError.details 是递归键控的 _errors 树，不是扁平 map，需要递归遍历才能定位到具体字段。

状态码到动作的映射。 技能提供一张完整的状态码表：400 修输入不重试、401 换凭证、403 查权限、415 改 Content-Type、429 读 X-RateLimit-Reset 加抖动退避、500/503 指数退避最多 3–5 次、504 改 stream: true 或缩短上下文。402 是唯一的分支场景——Bearer 认证提示去 venice.ai 充值，SIWE 认证则需要走 x402 充值流程并解析 PAYMENT-REQUIRED 响应头。

重试策略分层。 明确区分「永不重试」（400/401/403/415）、「修改后重试」（402 充值后重试、422 带 suggested_prompt 重试一次）、「退避重试」（429/500/503/504）三类，并在状态变更类调用上建议携带 Idempotency-Key 防止重复计费。

流式错误与关联 ID。 流式响应（chat、TTS、video-queue）中的 mid-stream 错误通过 SSE 事件传递，HTTP 状态码仍是 200，需要当作终止信号处理。X-Request-ID 在响应中出现时应保留下来用于工单排查，但不要假设所有端点都返回它。

适用边界与注意点

• 422 的 suggested_prompt 仅在音频生成管线（/audio/queue、/audio/retrieve）返回；图像和视频端点只有纯文本错误，无法自动挽救。
• /crypto/rpc/{network} 的 429 可能是 24 小时信用额度上限触发，而非每分钟速率限制，需检查 customMessage。
• /x402/top-up 返回 402 且没有 X-402-Payment 头是预期的发现流程响应，不是真正的失败。
• 大文件上传触发的 500 通常是上游模型主动中断，应减小 max_tokens 或图片尺寸，而不是盲目重试。
• 空流块（keepalive 产生的 data: [DONE] 或空行）不是错误，不要误判为异常。