Error codes
The error shapes and codes of the orchestrator, Venom Cloud, venom serve and the CLI, with what each means and whether a retry can help.
Every venom surface answers errors as JSON with a machine-readable code. Match on code, not on the message: messages are written for people and can change.
Shapes
The orchestrator and Venom Cloud use OpenAI's error shape, so OpenAI SDKs raise their usual exception types:
{"error": {"message": "budget for key ci exhausted until 2026-12-01", "type": "insufficient_quota", "code": "budget_exceeded", "param": null}}venom serve uses a smaller shape:
{"error": {"code": "session_not_found", "message": "no session s_123"}}CLI commands with --json print one line on stdout, and keep their exit code (0 success, 1 failure, 2 usage error):
{"ok": false, "error": {"code": "workflow_not_found", "message": "no workflow nope"}}A minimal client check, in Python with the openai SDK against the orchestrator:
from openai import OpenAI, APIStatusError
client = OpenAI(base_url="http://localhost:8787/v1", api_key="sk-…")
try:
client.chat.completions.create(model="venom-default", messages=[{"role": "user", "content": "hi"}])
except APIStatusError as e:
code = (e.body or {}).get("code") if isinstance(e.body, dict) else None
print(e.status_code, code)Retry rules
| Status | Retry? |
|---|---|
| 400, 401, 403, 404, 413, 422 | No. Fix the request, the key or the configuration. |
| 408, 499 | Yes, once: the body was slow to arrive, or the client went away. |
| 409 | Depends on the code: busy and lease_lost can succeed later; batch_not_cancellable never will. |
429 rate_limit_exceeded, tpm_limit_exceeded |
Yes, after Retry-After when present, else back off. |
429 budget_exceeded, spend_cap_reached, spend_limit_reached, plan_request_limit |
No, until the budget resets (x-venom-budget-reset or x-venom-spend-reset). Where the answer carries x-should-retry: false, OpenAI SDKs skip their automatic retry. |
| 500, 502, 503, 504 | Yes, with backoff. The orchestrator has already tried every target of the route before answering. |
Orchestrator
The type is invalid_request_error for 4xx unless shown otherwise, rate_limit_error for rate limits and server_error for 5xx.
| Status | code |
Meaning |
|---|---|---|
| 400 | invalid_request, invalid_json, invalid_body, invalid_parameter, invalid_value, invalid_state |
The body or a parameter is malformed. param names the field when known. |
| 400 | missing_model |
No model in the request. |
| 400 | context_length_exceeded |
The prompt does not fit any target's context window. Only targets with a larger or unknown window are tried before this answer. |
| 400 | image_input_unavailable |
The request has images and no target of the route accepts them. |
| 400 | unsupported_endpoint, unsupported_request |
The model cannot serve this endpoint (a chat model on /v1/embeddings), or the request has a shape the target does not support. |
| 400 | stateful_request_unsupported |
A /v1/responses request that needs server-side state (previous_response_id, store) and no native Responses target. |
| 400 | model_not_tts |
/v1/audio/speech for a model no target can speak with. |
| 400 | invalid_service_tier, invalid_urgency, invalid_batch_wait |
An unknown value in x-venom-service-tier, x-venom-urgency or x-venom-batch-wait. |
| 400 | invalid_session, invalid_intent, invalid_idempotency_key |
x-venom-session, X-Venom-Intent (over 128 bytes) or Idempotency-Key (over 255 bytes) is invalid. |
| 400 | invalid_callback_url, callback_host_not_allowed |
x-venom-callback-url is malformed, or its host is not in batch_routing.callback_hosts. |
| 400 | invalid_search_request, invalid_rerank_request, invalid_decision_request |
A malformed /v1/search, /v1/rerank or /v1/systemone body. |
| 401 | invalid_api_key |
Missing or unknown client key, or the admin token is wrong on /admin/v1/*. |
| 402 | intent_budget_exceeded (type insufficient_quota) |
The intent named in X-Venom-Intent has spent its budget. |
| 403 | model_not_allowed |
The key may not use this model. |
| 403 | profile_forbidden |
The route profile in x-venom-profile admits no target this key may use. |
| 403 | unpriced_model |
A cloud model with no price, on a key with a budget: venom will not spend money it cannot count. |
| 403 | guardrail_blocked (type guardrail_blocked) |
A guardrail rule refused the request. |
| 404 | model_not_found |
No route or upstream serves the model. |
| 404 | not_found, unknown_url |
An unknown id (file, batch, response), or a path the orchestrator does not serve. |
| 405 | method_not_allowed |
Wrong HTTP method for the path. |
| 408 | request_timeout |
The request body did not arrive within 60 seconds. |
| 409 | batch_not_cancellable, batch_request_not_cancellable |
The batch has already finished. |
| 409 | file_in_use |
The file is read by an unfinished batch. |
| 409 | config_changed_on_disk |
An admin config write lost a race with an edit on disk; re-read and retry. |
| 413 | request_too_large |
The body is over defaults.max_body_bytes (32 MiB by default). |
| 422 | idempotency_key_reused |
The same Idempotency-Key with a different body. |
| 422 | reload_failed |
A config reload was rejected; the previous config keeps running. |
| 429 | rate_limit_exceeded |
The key's or route's requests-per-minute limit. Retry-After says when. |
| 429 | tpm_limit_exceeded |
The tokens-per-minute limit. No Retry-After. |
| 429 | budget_exceeded (type insufficient_quota) |
The key's budget is spent. x-venom-budget-reset says when it resets. |
| 499 | client_closed |
Logged only: the client disconnected before the answer. |
| 500 | internal_error, store_error, routing_unavailable, usage_unavailable |
A fault inside the orchestrator or its SQLite store. |
| 502 | upstream_error, upstream_broken |
The upstream failed, or broke a stream after the first byte (the stream cannot fall back once bytes went out). |
| 502 | upstream_auth_failed |
The orchestrator's own provider key was refused. The client's key is fine; tell the operator. |
| 502 | search_failed |
Every search backend failed. |
| 503 | model_unavailable |
Every target of the route failed or is open-circuited; the message names each target and why. |
| 503 | no_upstream |
The route's only upstreams lack a credential; the message names the missing variable. |
| 503 | intent_ledger_full |
Over 100,000 distinct intents are tracked. |
Upstream errors pass through in their own status where that helps the client. An Anthropic 529 overloaded_error becomes a 503 so the route falls back.
Venom Cloud
The client surface (/v1/*) uses OpenAI types; the daemon and admin surfaces use type: "mesh_error".
| Status | code |
Meaning |
|---|---|---|
| 400 | invalid_request, invalid_decision_request |
A malformed request. |
| 401 | invalid_api_key, key_expired |
Unknown or expired vck_ key. |
| 403 | model_not_allowed, unpriced_model, profile_forbidden |
As on the orchestrator; model_not_allowed carries a reason. |
| 403 | prompt_blocked |
An organisation prompt filter refused the request; filter names it. |
| 403 | plan_limit_reached |
The organisation's plan does not allow this; upgrade_url says where to change it. |
| 404 | model_not_found |
No eligible daemon or provider serves the model. |
| 409 | idempotency_conflict |
The Idempotency-Key names a job that already finished; x-venom-job is its id. |
| 413 | request_too_large |
Over 4 MiB through the relay. Use direct mode for larger bodies. |
| 429 | rate_limit_exceeded, budget_exceeded, spend_cap_reached, spend_limit_reached, plan_request_limit |
A rate limit, budget, spend cap or plan limit. Spend guards add error.budget and error.suggested_model. |
| 502 | daemon_error |
Every attempt failed before the first byte. |
| 503 | no_daemon_available |
No daemon can take the request; reasons and the message say why and what to do. |
| 503 | no_direct_path |
x-venom-mesh-mode: direct and no daemon endpoint is reachable from the client. |
| 503 | mesh_unavailable |
The cloud's database is down. |
| 503 | session_daemon_unavailable |
A remote venom serve session's daemon is gone; resume the session. |
| 503 | prompt_classifier_unavailable |
The organisation's prompt classifier did not answer and fails closed. |
| 504 | dispatch_timeout |
No daemon accepted the job in time. |
| stream event | stream_time_limit, daemon_lost, daemon_error |
Errors after the first byte of a relayed stream, sent as an SSE error event. stream_time_limit can be resumed. |
Daemon-facing codes (daemon_unauthorized, daemon_revoked, join_token_invalid, join_token_expired, job_taken, job_gone, daemon_name_taken, daemon_upgrade_required) and ticket codes on a daemon's /v1 (ticket_invalid, ticket_expired, ticket_audience, ticket_replayed, ticket_team_not_accepted) appear in daemon logs, not in client answers.
venom serve
| Status | code |
Meaning |
|---|---|---|
| 400 | bad_request, invalid_json |
A malformed request. |
| 400 | unknown_model, images_not_supported, prompt_rejected |
The model is unknown, takes no images, or a hook refused the prompt. |
| 400 | not_a_directory, not_a_file, not_text, not_persisted, import_failed |
A path or session that cannot be used this way. |
| 401 | unauthorized |
Missing or wrong bearer token (VENOM_SERVER_TOKEN). |
| 403 | path_outside, path_protected, read_denied, write_denied |
The path is outside every --root, protected, or refused by the permission rules. |
| 403 | policy_forbidden, sudo_forbidden |
The organisation policy forbids it, or sudo mode is not allowed. |
| 403 | csrf_failed |
The mobile page's request lacked its x-venom-csrf token. |
| 404 | session_not_found, agent_not_found, file_not_found, question_not_found, inbox_item_not_found, schedule_not_found, run_not_found, output_not_found, not_found |
The named thing does not exist. |
| 405 | method_not_allowed |
Wrong HTTP method. |
| 409 | busy |
The session is already running a prompt; use steer or follow_up, or wait. |
| 409 | lease_lost, handoff_failed, saved_session_open |
Another machine holds the session's lease, a handoff failed, or the saved session is already open. |
| 409 | inbox_item_resolved, schedule_running |
Already resolved, or the schedule is already running. |
| 413 | body_too_large, too_large |
The body is over the limit (1 MiB, 16 MiB for a prompt), or a file is too large to read. |
| 429 | too_many_sessions |
The session limit is reached (8 by default); close one first. |
| 500 | internal, policy_error, session_create_failed |
A fault in the server. |
| 503 | shutting_down |
The server is stopping. |
Tool errors inside a session
When a tool call fails, the model sees a message, and the event carries a structured code at details.venomError (schema packages/harness/error-contract.schema.json): for example edit_mismatch (re-read, then retry), locked (another agent holds the file; retry later), timeout (retryable, with partial output), step_failed (a browser batch step failed), cleanup_incomplete (processes survived a kill) and internal. Apps on venom serve or the harness can branch on these instead of parsing text.
The team keeps a ledger of user-visible messages ranked by harm, the cost of a wrong reading: a retry loop, a false claim to the user, a half-done change, a lost clue. Messages at the top get rewritten first. One example: a denial in a session that could not ask anyone now says that nobody refused, and how to allow the call, instead of "the user denied this call".