venice-errors
Skill2 starsChanged 5 months agoMITView on GitHub
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.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- veniceai/skillstheir own version, first seen Oct 13, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- veniceai/skills★ 171same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository19 other files it gives its agents.
- cheaptokensSkill
- venice-api-keysSkill
- venice-api-overviewSkill
- venice-audio-musicSkill
- venice-audio-speechSkill
- venice-audio-transcriptionSkill
- venice-augmentSkill
- venice-authSkill
- venice-billingSkill
- venice-charactersSkill
- venice-chatSkill
- venice-crypto-rpcSkill
- venice-embeddingsSkill
- venice-image-editSkill
- venice-image-generateSkill
- venice-modelsSkill
- venice-responsesSkill
- venice-videoSkill
- venice-x402Skill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Every Venice endpoint returns one of four error shapes.
- Very specific: line 135
Use Idempotency-Key (e.g. on /crypto/rpc/{network}) so retries can't double-bill state-mutating calls.
- Very specific: line 196
Treat them as terminal — the underlying connection is closed.
- Very specific: line 209
Don't treat an empty stream chunk as an error — send-keepalives look like data: [DONE] or empty lines.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 SIWE 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"],
"topUpInstructions": {
"step1": "POST /api/v1/x402/top-up with no payment header to get payment requirements",
"step2": "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": { ... SIWE template ... }
}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
| Status | Body | Meaning | What to do |
400 Bad Request | DetailedError | Malformed input. Zod details identifies the field. | Fix and re-send. Don't retry. |
401 Unauthorized | StandardError | Missing / invalid Bearer API key or SIWE. | Rotate credentials. Don't retry. |
402 Payment Required | Bearer: 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 Forbidden | StandardError | Valid 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 Type | StandardError | Wrong Content-Type (e.g. JSON sent to a multipart endpoint, or vice versa). | Fix headers. Don't retry. |
422 Unprocessable Entity | ContentViolationError 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 Requests | StandardError | Rate 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 Error | StandardError | Unexpected failure. | Retry with exponential backoff + idempotency key where supported. |
503 Service Unavailable | StandardError | Upstream model / service temporarily down. | Retry with backoff. Consider a fallback model. |
504 Gateway Timeout | StandardError | Upstream slow. Mostly on /chat/completions with huge contexts. | Switch to stream: true or shorter prompts. |
Rate-limit headers (429)
Emitted on /crypto/rpc/{network}:
| Header | Meaning |
X-RateLimit-Limit | Per-minute request cap for your tier (paid = 100, staff = 1000 on crypto RPC). |
X-RateLimit-Remaining | Requests remaining in the current 60-second window. |
X-RateLimit-Reset | Unix timestamp in seconds when the window resets. |
Additionally, LlmInferenceError model-overloaded conditions set a Retry-After header (seconds) on the 429 — honor it when present.
Inference endpoints (chat, image, audio, video) use a per-API-key tier defined via /api_keys/rate_limits. See venice-api-keys to pre-fetch your caps, and venice-billing for DIEM/USD usage.
Response headers on 402 (x402)
| Header | Notes |
PAYMENT-REQUIRED | Base64-encoded JSON of the x402 v2 paymentRequired object (x402Version, error, resource, accepts[], optional extensions['sign-in-with-x']). Protocol-level discovery — parse even if you don't parse the JSON body. |
Retry strategy
Never retry
400— bad input. Fix the request.401— bad auth. Fix credentials.403— not entitled. Don't hammer.415— wrongContent-Type.
Retry with modification
402(x402) — run top-up then retry.402(Bearer) — surface to user; top up at venice.ai.422withsuggested_prompt— one retry with the safer prompt.
Retry with backoff
429— back off for at leastX-RateLimit-Reset - now(). Add jitter.500/503/504— exponential backoff (e.g. 0.5s, 1s, 2s, 4s, 8s), capped at ~30s. 3–5 retries max.- Use
Idempotency-Key(e.g. on/crypto/rpc/{network}) so retries can't double-bill state-mutating calls.
Reference retry loop
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 { status } = res
if ([400, 401, 403, 415].includes(status)) {
throw Object.assign(new Error(body.error ?? 'Venice error'), { status, body })
}
if (status === 402 && body.code === 'PAYMENT_REQUIRED') {
await topUpX402(body.suggestedTopUpUsd)
continue
}
if (status === 422) {
throw Object.assign(new Error('Content policy'), { status, body })
}
if (status === 429) {
const retryAfterSec = Number(res.headers.get('retry-after'))
const resetSec = Number(res.headers.get('x-ratelimit-reset'))
const waitMs = !Number.isNaN(retryAfterSec) && retryAfterSec > 0
? retryAfterSec * 1000
: !Number.isNaN(resetSec) && resetSec > 0
? Math.max(resetSec * 1000 - Date.now(), delay)
: delay
await sleep(waitMs + Math.random() * 250)
delay *= 2
continue
}
if (status >= 500 && attempt < maxRetries) {
await sleep(delay + Math.random() * 250)
delay *= 2
continue
}
throw Object.assign(new Error(body.error ?? 'Venice error'), { status, body })
}
throw new Error('Exceeded max retries')
}Streaming errors
Streaming responses (stream: true on chat, TTS, video-queue progress) deliver mid-stream errors as SSE events:
data: {"error": {"type": "…", "message": "…"}}Treat them as terminal — the underlying connection is closed. The HTTP status is 200 because a successful stream can't be changed mid-flight.
Request-ID correlation
When present on a response, keep the X-Request-ID header. Include it in support tickets — Venice keys diagnostic logs by this ID. /crypto/rpc/* routes set it explicitly; many inference routes also include it, but don't assume it's universal — fall back to your own client-side correlation ID.
Common gotchas
- A
402from/x402/top-upwith noX-402-Paymentheader is the expected discovery response, not an error. Seevenice-x402. - A
500on/chat/completionswith a huge file upload often means the upstream model chose to abort — reducemax_tokens/ image size rather than blindly retrying. 429on/crypto/rpc/{network}may mean the 24-hour credit cap tripped, not the per-minute one. CheckcustomMessage.DetailedError.detailsis a Zod_errorstree, not a flat map. Walk it recursively.- Some endpoints (image generation) echo
X-Rate-Limitvariants — treat any header whose name starts withX-RateLimitas advisory. - Don't treat an empty
streamchunk as an error — send-keepalives look likedata: [DONE]or empty lines.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

