---
title: Error codes
description: 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.
section: reference
order: 30
audience: [user, operator, builder, agent]
sources: [services/go-orchestrator/internal/proxy/proxy.go, services/nodejs-cloud/lib/http/errors.ts, packages/harness-server/src/server.ts, packages/harness-server/openapi.yaml, docs/cloud-mesh.md, docs/headless.md, docs/error-message-ledger.md, packages/harness/error-contract.schema.json]
features: [reference.doc-error-message-ledger]
---

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 {#shapes}

The orchestrator and Venom Cloud use OpenAI's error shape, so OpenAI SDKs raise their usual exception types:

```json
{"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:

```json
{"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):

```json
{"ok": false, "error": {"code": "workflow_not_found", "message": "no workflow nope"}}
```

A minimal client check, in Python with the `openai` SDK against the orchestrator:

```python
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 {#retry}

| 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 {#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 {#cloud}

The client surface (`/v1/*`) uses OpenAI `type`s; 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 {#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 {#tool-errors}

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

## Related

- [x-venom headers](/docs/reference/headers.md)
- [Limits and defaults](/docs/reference/limits.md)
- [Architecture, ports and contracts](/docs/reference/architecture.md)
