Skip to content
Docs menu

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.

View .md

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".