venice-errors

Venice のエラーと再試行

Venice のエラーの多くは { "error": "<message>" } ですが、いくつかの経路では構造が追加されます。受け取った形式を把握しておくと、適切な対処ができます。

エラーボディの形式

1. StandardError - シンプルなメッセージ

4xx／5xx でのデフォルトです。

{ "error": "Authentication failed" }

2. DetailedError - スキーマ検証の失敗（400）

リクエストが Venice 独自のスキーマに適合しない場合、details はネストされたツリー（フィールドをキーとして再帰的に構成される _errors）で、issues はフラットな問題のリストです。一部の画像、動画、上流での失敗では、details が単なる文字列として返されるため、内容をたどる前に型を確認してください。

{
  "error": "Invalid request parameters",
  "details": {
    "_errors": [],
    "type": { "_errors": ["Invalid enum value. Expected 'asr' | 'decision' | … , received 'bogus'", "Invalid enum value. Expected 'all' | 'code', received 'bogus'"] }
  },
  "issues": [
    { "code": "invalid_union", "unionErrors": [ … ], "path": ["type"], "message": "Invalid input" }
  ]
}

（これは GET /models?type=bogus に対する実際のレスポンスです。）

多くの 400 は通常の StandardError です。両方の形式を処理してください。details ／ issues を表示し、再試行はしないでください。

3. OpenAI 形式のコンテキスト超過（400、チャット）

{
  "error": {
    "message": "Your request exceeds the model's maximum context. Please reduce your prompt or completion length.",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "context_length_exceeded"
  }
}

ここでは error がオブジェクトであるため、OpenAI SDK はこれを検出できます。message は Venice が抽出できた場合はプロバイダーの文言、抽出できなかった場合は上記のテキストになります。message ではなく code を照合してください。プロンプトを短くするか、max_completion_tokens を減らしてください。

4. 上流プロバイダーによる拒否（400）

リクエストが Venice のスキーマを通過したものの、モデルプロバイダーに拒否された場合、Venice はプロバイダーのメッセージを返します。また、リクエストを追跡するルート（たとえば chat。/decisions では省略されます）には request_id も含まれます。

{ "error": "<provider's validation message>", "request_id": "…" }

FastAPI 形式の検証エラー（たとえば、POST /decisions の背後にある TypeSafe プロバイダーが返す 422）は、最大 5 件の field.path: message を ; でつないだ 400 として通知されます。Venice がメッセージを抽出できない場合は、"Invalid request parameters. For assistance, please reach out to [email protected]" が返されます。request_id がある場合は、その後に " and reference request ID: <id>" が続きます。これらは chat ／ responses の寛容な未対応機能予算の対象となります（エラー予算 を参照）。入力を修正し、サポートへの問い合わせ時に request_id を伝えてください。

5. ContentViolationError - コンテンツポリシーによる 422

{
  "error": "Your prompt violates the content policy of Venice.ai or the model provider",
  "suggested_prompt": "A cinematic instrumental track inspired by stormy weather and dramatic tension."
}

chat、responses、画像編集、複数画像編集、音声生成で返されます。/image/generate では使用されません（画像がブロックされた場合、x-venice-is-content-violation: true を付けて 200 が返されます）。また、動画のコンテンツポリシーによる拒否はキューではなく /video/retrieve で返されます。suggested_prompt は /audio/queue と /audio/retrieve でのみ出力されます。存在する場合は、ユーザーの同意を得てからそれを使って一度だけ再試行してください。その他の 422 には、"Your input was blocked by content moderation." や、メディア検証の失敗（画像が大きすぎる、不適切なアスペクト比、音声／動画の長さが範囲外、ASR が音声を処理できないなど）が含まれます。

6. ProviderContentPolicyError - /video/retrieve の 422

{
  "error": {
    "message": "The selected model provider rejected this request due to its content policies. Credits have been refunded. Try using <model> instead.",
    "type": "provider_content_policy",
    "credits_refunded": true,
    "recommended_model": "<model id>"
  }
}

credits_refunded を確認してください。必要に応じて、recommended_model を使って再度キューに登録してください。

7. PayloadTooLargeError - 413

{ "code": "PAYLOAD_TOO_LARGE", "error": "File exceeds the maximum allowed size of 25 MB." }

8. x402 の 402 レスポンスボディ

402 には 2 つの形式があります。どちらの場合も PAYMENT-REQUIRED ヘッダーが設定されます。認証情報がない場合の形式は、Bearer 認証のみのルート（/api_keys*、/billing/*、/characters*）を含む、認証情報を必要とするすべてのルートで返されます。ただし、この形式の支払いオプションは適用されません。

認証情報がまったくない場合 - x402 v2 の検出（401 ではありません）：

{
  "x402Version": 2,
  "error": "Authentication required",
  "resource": { "url": "https://api.venice.ai/api/v1/chat/completions", "description": "Venice API", "mimeType": "application/json" },
  "accepts": [ { "scheme": "exact", "network": "eip155:8453", "…": "…" }, { "scheme": "exact", "network": "solana", "…": "…" } ],
  "extensions": { "sign-in-with-x": { "info": { "domain": "api.venice.ai", "statement": "Sign in to Venice AI", "…": "…" }, "supportedChains": [ … ] } },
  "authOptions": {
    "apiKey": { "header": "Authorization: Bearer YOUR_API_KEY", "getKey": "https://venice.ai/settings/api", "docs": "…" },
    "x402Wallet": { "header": "SIGN-IN-WITH-X", "legacyHeader": "X-Sign-In-With-X", "topUp": "POST /api/v1/x402/top-up", "docs": "…" }
  }
}

サインイン済みのウォレット残高が最低額の $0.10 を下回る場合 - code: "PAYMENT_REQUIRED" で判別します：

{
  "error": "Payment required",
  "code": "PAYMENT_REQUIRED",
  "reason": "insufficient_balance",
  "currentBalanceUsd": 0.01,
  "minimumBalanceUsd": 0.1,
  "description": "Venice API",
  "suggestedTopUpUsd": 10,
  "minimumTopUpUsd": 5,
  "supportedTokens": ["USDC"],
  "supportedChains": ["base", "solana"],
  "topUpInstructions": {
    "step1": "POST /api/v1/x402/top-up with no payment header to get payment requirements",
    "step2": "Choose a payment option from accepts and sign a USDC transfer authorization using the x402 SDK (createPaymentHeader)",
    "step3": "POST /api/v1/x402/top-up with the signed X-402-Payment header",
    "receiverWallet": "0x…",
    "tokenAddress": "0x…",
    "tokenDecimals": 6,
    "network": "eip155:8453",
    "minimumAmountUsd": 5
  },
  "siwxChallenge": { "info": { … }, "supportedChains": [ … ] }
}

topUpInstructions には Base の決済レールのみが記載されています。Solana で支払う場合は POST /x402/top-up から accepts[] を読み取り、正規のヘッダーである PAYMENT-SIGNATURE を送信してください（X-402-Payment / X-PAYMENT も引き続き使用できます）。PAYMENT-REQUIRED ヘッダーは、x402 の base64 エンコードされた paymentRequired オブジェクト（x402Version、error、resource、accepts[]、extensions）であり、レスポンスボディではありません。詳しくは venice-x402 をご覧ください。

API キーの 402 はシンプルな形式です：{ "error": "Insufficient USD or Diem balance to complete request. Visit https://venice.ai/settings/api to add credits." }、またはキーごとの利用上限に関するバリエーション（"API key DIEM spend limit exceeded…" / "API key USD spend limit exceeded…"）です。ウォレットの場合、クレジットが $0.10 の最低額を上回っていても、このリクエストの提示価格には足りないと、同じシンプルな "Insufficient USD or Diem balance…" のレスポンスボディが返ることがあります（例：/video/queue、/audio/queue）。チャージして再試行してください。

9. x402 のサインイン失敗（401）

推論ルートでは、不正な SIGN-IN-WITH-X に対して { "error": "<message>", "code": "X402_SIGN_IN_…" } が返されます（例：X402_SIGN_IN_EXPIRED、X402_SIGN_IN_NONCE_REUSED）。/x402/balance と /x402/transactions は、汎用の { "error": "Invalid Sign-in-with-x signature" } を返します。すべてのコードについては venice-auth をご覧ください。

ステータスコード一覧

ステータス	一般的な本文	意味	対応
400	DetailedError、StandardError、コンテキスト超過オブジェクト、または上流の { error, request_id }	入力形式の誤り、model の欠落または文字列以外の指定（プレーンな "model is required" ／ "model must be a string"）、このモデルでサポートされていないオプション、プロバイダーによる拒否、無効な JSON（"Invalid JSON request"）、または Content-Type が JSON でも multipart でもない POST（"'Content-Type' must be 'application/json'"）。推論ルートではなく /x402/top-up に送るべき x402 決済ヘッダーを送信した場合の PAYMENT_HEADER_NOT_ACCEPTED も含まれます。	修正して再送信してください。再試行しないでください。
401	StandardError または { error, code }	不明、有効期限切れ、または取り消し済みの API キー（「Authentication failed」）、管理者専用ルートでの ADMIN 以外のキー（「Admin API key required」）、無効な SIWX、または「This model is only available to Pro users」（Pro 専用モデルで有料プランのない API キーアカウント）。	認証情報／プランを修正してください。再試行しないでください。
402	形式 8 を参照	認証情報なし（ディスカバリー）、ウォレット残高不足、または API キーアカウント／キーの利用上限到達。	x402：チャージしてから再試行してください。API キー：クレジットを追加するか、キーの上限を引き上げてください。
403	StandardError	利用資格はあるもののアクセス不可：お住まいの国でモデルがブロックされている（regionRestrictions）、キーの modelPrivacy でモデルが禁止されている、API アクセスが無効になっている、SIWX ウォレットとパスのウォレットが一致しない。	再試行しないでください。
404	StandardError	不明なモデル（「Specified model not found: …」。候補の提示や「has been deprecated. Please use …」のヒントが付く場合があります）、不明なキャラクター、期限切れのメディア。	ID を修正してください。
409	{ error: { code: "needs_consent", message }, consent_flow, face_media_roles, consent, docs_url }（動画）または { error, message, details }（x402）	/video/queue で同意が必要（非掲載のモデル ID の場合のみ。掲載済みモデルでは同意を求めません）、または処理済み、あるいは決済確定待ちの x402 チャージ（error にコードが入り、例："PAYMENT_IN_PROGRESS" — しばらくしてから再試行してください）。	venice-video ／ venice-x402 を参照してください。
410	StandardError	廃止されたエンドポイント（GET /billing/usage、POST /video/transcriptions）。メッセージに移行先が記載されています。	移行してください。再試行は絶対にしないでください。
413	PayloadTooLargeError	JSON 本文が 35 MB を超えている（"Request body exceeds the maximum allowed size."）、または multipart ファイルが 25 MB を超えている。	アップロードサイズを小さくしてください。
415	StandardError	まれなケース：本文が空の /image/multi-edit、またはサーバーがデコードできない Content-Encoding ／文字セットの本文（"Request encoding is not supported"）。どのルートでも Content-Type が誤っている場合は 400 が返されます。	ヘッダーを修正してください。
422	ContentViolationError、ProviderContentPolicyError、または StandardError	コンテンツポリシー違反、または処理できないメディア（寸法、長さ、読み取り不能な音声）。	プロンプト／メディアを変更してください。suggested_prompt が提示されている場合は、それを使って 1 回再試行してください。
429	StandardError または { error, code }	リクエスト／トークンのレート制限、エラーバジェットの上限到達、モデルの過負荷、x402 の同時実行制限（X402_CONCURRENCY_LIMIT、ウォレットごとに同時実行 5 件）、またはルートごとの制限（暗号資産 RPC、/x402/*、/tee/*、廃止されたエンドポイント）。	下記のレート制限を参照してください。
500	StandardError	予期しないエラー。	待ち時間を延ばしながら再試行してください。
502	StandardError	上流のエラー（TTS、ASR、TEE、動画の取得）。	待ち時間を延ばしながら再試行してください。
503	StandardError	モデルがオフライン、または処理能力の上限に達しています。	待ち時間を延ばしながら再試行してください。代替モデルの利用も検討してください。
504	StandardError	リクエストがタイムアウトしました。主に非ストリーミングのチャットで発生します。	stream: true を指定するか、リクエストの規模を小さくしてください。

レート制限とそのヘッダー

独立したヘッダー系列が3つあります。プレフィックスは共通していますが、単位は異なるため、正確な名前を確認してください。

ヘッダー	出力元	リセット単位
x-ratelimit-limit-requests、x-ratelimit-remaining-requests、x-ratelimit-reset-requests（および -tokens のバリエーション）	推論ルートのモデルレート制限（アカウントごと、モデルごと。1分／1日のリクエスト数と1分あたりのトークン数）	Unix ミリ秒
x-ratelimit-remaining、x-ratelimit-resets	エラーバジェット。認証情報が必要なルートのほとんどのレスポンスに含まれます（認証情報不要の 402 には含まれません）	Unix ミリ秒
X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset	/crypto/rpc/{network}。1分あたりの上限による 429 の場合のみ	Unix 秒

モデル制限による 429 のメッセージは "Rate limit exceeded" です。事前に GET /api_keys/rate_limits で上限を取得してください（Bearer キーのみ）。過去のヒットは GET /api_keys/rate_limits/log で確認できます。このエンドポイントには ADMIN キーが必要です。INFERENCE キーでは 401 "Admin API key required" が返されます（venice-api-keys）。

ルートごとの制限では、これらのヘッダーなしで 429 が返されます。/x402/top-up（IP ごとに10回／分）、/x402/balance（ウォレットごとに30回／分）、/x402/transactions（ウォレットごとに20回／分）では "Rate limit exceeded. Please try again later." が返されます。/tee/*（IP ごとに10回／分）では "Rate limit exceeded." が返されます。廃止されたエンドポイントでは、IP ごとに60回／分まで許可されます。

上流の過負荷：Retry-After（秒単位、デフォルトは30）と、"The model is currently overloaded. Please try again later." のようなメッセージを伴う 429 が返されます。Retry-After に従ってください。

エラーバジェット

成功したリクエストより、失敗したリクエストのほうが厳しくレート制限されます。

バジェット	閾値	カウント対象	ログ上の名前
失敗したリクエスト	30秒あたり50件	429 を除くすべての 4xx（5xx はカウントされません）	FAILED_REQUESTS
未対応機能のリクエスト	30秒あたり200件。/chat/completions と /responses のみ	モデルが対応していない機能を要求するリクエスト、または有効なリクエストに対するプロバイダー側の拒否	UNSUPPORTED_FEATURE_REQUESTS

バケットは API キーごと（x402 の場合は IP ごと）、model ごと、OpenAI の user 文字列ごとに分かれます。マルチパートアップロードでは model／user が時間内に取得できないため、キー（または IP）のバケットを共有します。バケットが枯渇すると、リセットされるまで、その中のすべてのリクエストに次の内容で 429 が返されます。

Too many failed attempts (> 50) resulting in a non-success status code. Please wait 30 seconds and try again. See https://docs.venice.ai/api-reference/rate-limiting for more information.

未対応機能のバケットでは、同じ文言で > 200 が使われます。そのため、400／401／402 を無条件に再試行するクライアントは、自身をロックアウトしてしまいます。再試行不可のエラーでは停止してください（認証情報不要の 402、Content-Type と無効な JSON による 400、JSON ボディが35 MBを超える場合の 413 は、バジェットの確認前に拒否されるためカウントされません）。

再試行戦略

再試行しない

400、401、403、404、410、413、415 — リクエスト、認証情報、またはエンドポイントを修正してください。

修正して再試行

• code: "PAYMENT_REQUIRED" を伴う 402 — ユーザーの利用上限内で /x402/top-up からチャージしてから再試行してください（venice-x402 を参照）。
• x402Version を伴う 402（認証情報なし）— Authorization: Bearer … を追加するか、ウォレットを受け付けるルートでは SIGN-IN-WITH-X を使用してください。Bearer 専用のルート（/api_keys*、/billing/*、/characters*）では SIWX は 401 で拒否されるため、そこでは Bearer キーを送信してください。
• ウォレット認証を使う再試行では、新しく署名した SIGN-IN-WITH-X ヘッダーが必要です。各 nonce は一度だけ受け付けられるため、元のヘッダーを再送すると X402_SIGN_IN_NONCE_REUSED で失敗します。
• API キーでの 402 — ユーザーに提示してください。
• suggested_prompt を伴う 422 — より安全なプロンプトで1回再試行してください。

バックオフ付き再試行

• 429 - Retry-After がある場合はその時間だけ待ち、ない場合は該当するリセットヘッダーで指定された時刻まで待ちます。ジッターを加えます。
• 500 / 502 / 503 / 504 - 指数バックオフ（0.5 秒、1 秒、2 秒、4 秒、8 秒）を行い、約 30 秒を上限として、再試行は最大 3～5 回にします。
• 非同期キュー（/video/queue、/audio/queue、/audio/voice-changer/queue）では、ジョブの完了前に課金されることがあります（API キーを使った呼び出しは、キューに追加された時点で前払いされます）。キューの応答が失われた場合は、再度キューに追加せず、retrieve でポーリングしてください。Idempotency-Key がサポートされているのは /crypto/rpc/{network} のみです。

再試行ループの例

const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))

function waitMs(res: Response, fallback: number): number {
  const retryAfter = Number(res.headers.get('retry-after'))
  if (retryAfter > 0) return retryAfter * 1000
  const msReset = Number(res.headers.get('x-ratelimit-reset-requests') ?? res.headers.get('x-ratelimit-resets'))
  if (msReset > 0) return Math.max(msReset - Date.now(), fallback)
  const secReset = Number(res.headers.get('x-ratelimit-reset')) // crypto RPC
  if (secReset > 0) return Math.max(secReset * 1000 - Date.now(), fallback)
  return fallback
}

// fn must build a fresh SIGN-IN-WITH-X header on every call; nonces are single-use.
async function callVenice<T>(fn: () => Promise<Response>): Promise<T> {
  const maxRetries = 5
  let delay = 500
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fn()
    if (res.ok) return res.json() as Promise<T>

    const body = await res.clone().json().catch(() => ({}))
    const message = typeof body.error === 'string' ? body.error : body.error?.message ?? 'Venice error'
    const fail = () => Object.assign(new Error(message), { status: res.status, body })

    if ([400, 401, 403, 404, 410, 413, 415, 422].includes(res.status)) throw fail()

    if (res.status === 402) {
      // topUpAllowed must enforce the user's cap and check GET /x402/balance first.
      if (body.code === 'PAYMENT_REQUIRED' && attempt === 0 && (await topUpAllowed())) {
        await topUpX402(Math.min(body.suggestedTopUpUsd, USER_TOP_UP_CAP_USD))
        continue
      }
      throw fail()
    }

    if ((res.status === 429 || res.status >= 500) && attempt < maxRetries) {
      await sleep((res.status === 429 ? waitMs(res, delay) : delay) + Math.random() * 250)
      delay = Math.min(delay * 2, 30_000)
      continue
    }

    throw fail()
  }
  throw new Error('Exceeded max retries')
}

ストリーミングエラー

/chat/completions のストリームでヘッダー送信後にエラーが発生した場合、HTTP ステータスは 200 のままで、エラーがインバンドで送信された後、終端子が続きます。

data: {"error":{"message":"…","type":"server_error","code":"model_overloaded","param":null,"retry_after":30}}
data: [DONE]

過負荷エラーでは type: "server_error"、code: "model_overloaded" が使われ、retry_after（秒）が含まれる場合があります。それ以外の上流の障害では、type: "api_error" と code: "upstream_error" または特定のコード（例：e2ee_attestation_stale）が使われます。このイベントは終端として扱ってください。

リクエスト ID の相関付け

チャットで上流から拒否された場合のレスポンス本文には request_id が含まれ、/crypto/rpc/{network} ではプロキシされたレスポンスに X-Request-ID ヘッダーが設定されます。サポートへの問い合わせには、いずれか一方と、レスポンスヘッダーの x-venice-version を含めてください。それ以外のルートではリクエスト ID が保証されないため、クライアント側でも独自の相関 ID を保持してください。

よくある注意点

• /x402/top-up から支払いヘッダーなしで返される 402 は、想定される検出レスポンスです。
• 推論ルートでの 402（401 ではありません）は、通常、認証ヘッダーをまったく送信していないことを意味します。
• サフィックスのない x-ratelimit-remaining は、リクエストのクォータではなく、エラーバジェットを示します。
• 429 は複数の異なる制限（モデル制限、エラーバジェット、過負荷、x402 の同時実行数、ルートごとの上限）によって発生する場合があります。待ち時間を決める前に、メッセージとヘッダーを確認してください。
• スキーマ検証による 400 では、DetailedError.details はフラットなマップではなく、ネストされた _errors ツリーです。一部の画像／動画／上流エラーでは、単なる文字列として送られます。たどる前に型を確認してください。
• SSE ストリームでは、data: [DONE] がストリームの終了を示します（エラーチャンクの後も同様）。キープアライブではありません。