Venice 错误与重试

要解决的问题

调用 Venice 接口时，4xx/5xx 错误响应的结构并不统一：同一个端点可能返回简单的标准错误，也可能返回带有 Zod 校验树或内容策略提示的详细错误。开发者如果只按一种格式解析，容易在生产环境出现解析失败、无效重试，甚至绕过内容策略的问题。

核心处理逻辑

本技能将 Venice 错误归纳为四类可区分的响应形状，并提供对应的处理动作：

• StandardError：常见的 4xx/5xx 默认结构，只包含简单的 error 消息。适合统一兜底，但不要假设所有 400 都只有这一种形状。
• DetailedError：出现在部分 400 响应中，附带 details（Zod format() 树，字段递归键控）和扁平的 issues 数组。面向用户渲染这些字段，帮助修正请求体，但不要重试，因为请求结构本身有问题。
• ContentViolationError：422 内容策略拦截。若响应包含 suggested_prompt，在用户同意后，可用 prompt = suggested_prompt 重试一次。注意该字段目前只在 /audio/queue 与 /audio/retrieve 等音频生成管道返回，图像和视频端点只返回无建议的 Content policy violation。
• X402InferencePaymentRequired：仅在 x402 推理调用中，使用 SIWE 认证但余额不足时出现，以 code: "PAYMENT_REQUIRED" 判别。可根据 suggestedTopUpUsd 与 minimumTopUpUsd 提示用户充值，而非盲目重试。

适用边界与注意点

• 400 响应可能只有 StandardError，也可能带 details，必须两种都处理。
• 内容策略重试依赖 suggested_prompt 是否存在以及用户同意；图像、视频端点不会给出建议提示。
• suggestedTopUpUsd 和 minimumTopUpUsd 仅作为提示，具体充值流程由平台决定。
• 错误分类基于响应结构和 code 字段，应保留原始响应以便诊断。