Errors & limits
HTTP status codes shared across chat, images, and video inference unless noted.
402 is the one code that means two things depending on the route. On inference it means the confirmed balance is too low. On the funding routes (signup, refill, and browser top-up) it is the x402 challenge itself, and the body carries accepts with the payment requirements. So on a 402, read the body: accepts present means sign and pay, accepts absent means the balance needs funding first.
That reading applies to 402 and nowhere else. A 409 also arrives without accepts, and it means the opposite: money already moved, so paying on one spends twice.
| Code | Meaning | What to do |
|---|---|---|
400 | Invalid request | Fix the JSON body or use a live model from GET /v1/models. |
401 | Authentication failed | Send Authorization: Bearer pzero_…. Session cookies are not accepted on inference, refill, or /v1/agent/*. |
402 | Insufficient balance (inference) or payment challenge (funding) | On inference: confirmed USDC too low, so fund via POST /v1/x402/refill and wait for confirmation. On signup/refill/top-up: the body carries accepts, so sign it and retry. Either way no money has moved. |
403 | Payer mismatch (funding) | Payment wallet is not the Bearer account. Fix the payer before retrying. |
404 | Model not found | Use a live model id from GET /v1/models. |
409 | Money moved, request did not finish | Only on funding routes, and never with accepts. Do not pay again. reconciling: true means queued credit from the chain; reconciling: false means even that write failed, so keep transaction and quote it to support. On signup at the ten-key cap the body reads credited: true instead: money on the wallet, no key. On POST /v1/agent/keys it is the same cap with nothing paid. |
410 | Video media gone | Job refunded or expired; do not expect MP4 on retrieve. |
429 | Concurrency limit | key_concurrency_limit: too many completions in flight on this API key; retry after Retry-After (1s) or lower parallelism. buyer_concurrency_limit is the per-wallet gate (always on for images). |
500 | Internal / settle_failed | Safe to retry for non-streaming failures. You are not charged when settlement does not commit. |
502 | Provider error | Upstream could not complete. Safe to retry. |
503 | No supply / capacity | See 503 shape below. Raise max price only for no_eligible_supply. |
503 shape
Structured error.code values: no_eligible_supply, insufficient_routable_at_price, pool_empty, key_wait_timeout, keys_busy (video quote only).
no_eligible_supply means supply exists but sits above your ceiling, so retrying alone changes nothing. The body carries buyerMaxCents, cheapestPostedCents, and routableDiemAboveMax; send cheapestPostedCents to PATCH /v1/agent/max-price and the same request clears.
pool_empty means nothing is posted at any price. Only waiting helps.
insufficient_routable_at_price means offers at your price lack enough routable DIEM for this request. Body/headers may include eligibleRoutableDiem and maxEligibleOfferDiem. Raising max price does not help. Send a smaller job or retry later.
key_wait_timeout means chat/image/video queue timed out waiting for a Venice key. Retry.
keys_busy is POST /v1/video/quote only (no-wait select). All eligible keys are in flight. Retry shortly.
Hint headers when present: X-Pzero-Error-Code, X-Pzero-Buyer-Max-Cents, X-Pzero-Cheapest-Posted-Cents, X-Pzero-Routable-Diem-Above-Max, X-Pzero-Max-Eligible-Offer-Diem.
Streaming
On chat SSE, post-start failures arrive as an SSE data: error object instead of [DONE].
Tracing one request
Chat, image, and video queue responses carry X-Pzero-Request-Id and X-Pzero-Support-Reference when an attempt row was stored (including many error paths). Video readiness polls and POST /v1/video/quote send request id only: no support reference. Quote the support reference in a support request, or resolve it yourself at GET /v1/agent/requests/{support_reference}.
503 responses from chat, image, and video queue also carry the support reference of the attempt they recorded, in the header and in the error body.
Limits
- Funding: $1–$1,000 USDC per payment. See
POST /v1/x402/refill. - Ten active API keys per account;
POST /v1/agent/keysreturns409at the cap. - Per-key in-flight completions are capped (
429key_concurrency_limit). Images also enforce one in-flight job per wallet (buyer_concurrency_limit). - Signup carries a global fuse on facilitator calls (
429withRetry-After) because that route cannot attribute callers.