跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

venice-errors

Handle Venice API errors correctly. Covers the StandardError / DetailedError / ContentViolationError / X402InferencePaymentRequired body shapes, every meaningful status code (400, 401, 402, 403, 415, 422, 429, 500, 503, 504), the 402 PAYMENT-REQUIRED header used by x402 inference, 422 content-policy suggested_prompt retry pattern, 429 rate-limit headers, and an exponential-backoff retry strategy with idempotency.

veniceai · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add veniceai/skills --skill venice-errors

技能说明


name: venice-errors description: Handle Venice API errors correctly. Covers the StandardError / DetailedError / ContentViolationError / X402InferencePaymentRequired body shapes, every meaningful status code (400, 401, 402, 403, 415, 422, 429, 500, 503, 504), the 402 PAYMENT-REQUIRED header used by x402 inference, 422 content-policy suggested_prompt retry pattern, 429 rate-limit headers, and an exponential-backoff retry strategy with idempotency.

Venice errors & retries

Every Venice endpoint returns one of four error shapes. Knowing which shape you got tells you how to react.

Error body shapes

1. StandardError — simple message

The default shape for 4xx/5xx. Emitted when there's nothing structured to surface.

{ "error": "Unauthorized" }

2. DetailedError — Zod validation failure

Used for some 400 responses on malformed request bodies. When present, details is a Zod format() tree (_errors recursively keyed by field) alongside a flat issues array. Many 400s are plain StandardError without details — always handle both.

{
  "error": "Invalid request",
  "details": {
    "_errors": [],
    "messages": { "_errors": ["Field is required"] }
  },
  "issues": [
    { "code": "invalid_type", "path": ["messages"], "message": "Field is required" }
  ]
}

Render details / issues to the user so they can fix the input; don't retry — the request shape is wrong.

3. ContentViolationError — 422 content policy

Returned when a prompt trips content policy. suggested_prompt (a model-provided safe alternative) is currently emitted by the audio generation pipeline (/audio/queue, /audio/retrieve); image and video endpoints return { error: "Content policy violation" } without suggested_prompt.

{
  "error": "Content policy violation",
  "suggested_prompt": "A cinematic instrumental track inspired by stormy weather and dramatic tension."
}

Pattern — when suggested_prompt is present, retry once with prompt = suggested_prompt if the user consents.

4. X402InferencePaymentRequired — 402 on x402 inference calls

Returned only when the caller authenticated with SIWX and has insufficient credit. Discriminated by code: "PAYMENT_REQUIRED".

{
  "error": "Payment required",
  "code": "PAYMENT_REQUIRED",
  "message": "Insufficient x402 balance",
  "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": "<RECEIVER_WALLET_ADDRESS>",
    "tokenAddress": "<USDC_TOKEN_ADDRESS>",
    "tokenDecimals": 6,
    "network": "eip155:8453",
    "minimumAmountUsd": 5
  },
  "siwxChallenge": { ... SIWX template + supportedChains ... }
}

topUpInstructions describes the Base rail only, even when supportedChains includes Solana. Read accepts[] from POST /x402/top-up to pay on Solana.

The PAYMENT-REQUIRED response header carries a base64-encoded x402 v2 paymentRequired object (x402Version, error, resource, accepts[], optional extensions) — it is not the same JSON as the body. Protocol-level clients parse the header; human-facing clients parse the richer body. See venice-x402.

Status code map

StatusBodyMeaningWhat to do
400 Bad RequestDetailedErrorMalformed input. Zod details identifies the field.Fix and re-send. Don't retry.
401 UnauthorizedStandardErrorMissing / invalid Bearer API key or SIWE.Rotate credentials. Don't retry.
402 Payment RequiredBearer: StandardError with the configured message (e.g. { "error": "Insufficient balance" } — the handler's default path does not attach a code field). SIWE: X402InferencePaymentRequired + PAYMENT-REQUIRED header.Out of DIEM/USD/wallet credit.Bearer: top up at venice.ai. SIWE: run the x402 top-up flow.
403 ForbiddenStandardErrorValid auth but not entitled. Typical: trial-limited endpoint, beta model, API-key consumption cap hit, SIWE signer ≠ path wallet.Don't retry. Investigate entitlements.
415 Unsupported Media TypeStandardErrorWrong Content-Type (e.g. JSON sent to a multipart endpoint, or vice versa).Fix headers. Don't retry.
422 Unprocessable EntityContentViolationError on image/audio/video generation; plain { error } on other routes (e.g. ASR validation errors).Content policy violation on generation paths; schema-ish validation on others.On audio generation, optionally retry once with suggested_prompt. On others, fix input.
429 Too Many RequestsStandardErrorRate limit cap tripped. Also returned by /crypto/rpc/{network} when credit-per-day or concurrency cap tripped.Honor X-RateLimit-* headers, back off with jitter.
500 Internal Server ErrorStandardErrorUnexpected failure.Retry with exponential backoff + idempotency key where supported.
503 Service UnavailableStandardErrorUpstream model / service temporarily down.Retry with backoff. Consider a fallback model.
504 Gateway TimeoutStandardErrorUpstream slow. Mostly on /chat/completions with huge contexts.Switch to stream: true or shorter prompts.

Rate-limit headers (429)

Emitted on /crypto/rpc/{network}:

HeaderMeaning
X-RateLimit-LimitPer-minute request cap for your tier (paid = 100, staff = 1000 on crypto RPC).
X-RateLimit-RemainingRequests remaining in the current 60-second window.
X-RateLimit-ResetUnix timestamp in seconds when the window resets.
阅读完整来源 ↗