# Error codes

> Source: https://openwop.dev/errors/ · OpenWOP, the open-source protocol for multi-agent workflow orchestration.

The canonical OpenWOP v2 error envelope is `{ error, message, details? }` returned with the registered HTTP status. This page lists every code in the v2 error registry with its HTTP status and whether it is retriable.

Generated from [`spec/v2/errors.json`](https://github.com/openwop/openwop/blob/main/spec/v2/errors.json) at build time, so it cannot drift from the corpus. Envelope shape: [`core/errors.md`](https://openwop.dev/spec/v2/core/errors.html).

## Envelope shape

```json
{
  "error": "validation_error",
  "message": "Request body fails schema",
  "details": {
    "field": "workflowId",
    "reason": "missing"
  }
}
```

- `error` — machine-readable identifier: a registered code or a vendor code. Clients route on `error`, never on `message`. Stable within a major; new codes land additively.
- `message` — human-readable explanation, for people and logs only. Good practice (not a v2 rule): don't echo the offending input verbatim, since it can carry a prompt-injection payload or a credential.
- `details` — optional structured context; contextual data (conflict refs, trace ids, validation paths) lives here, never at a new top level. The body carries nothing else (`additionalProperties: false`).

The HTTP status code carries the primary classification; the `error` field disambiguates within the status class. A host MUST answer with the status the registry assigns to the code. Retry timing lives in the `Retry-After` header only — never in `details`.


## Codes by HTTP status



## Stability guarantees

Per [Versioning & compatibility](https://openwop.dev/versioning/):

- **New codes** land additively within a major. A client MUST accept an unknown code and MUST NOT act on it ([`overview.md`](https://openwop.dev/spec/v2/core/overview.html) §0); the HTTP status still classifies the response.
- **Existing codes** never change their HTTP status mapping or their semantic meaning within a major; renaming a code is a major-version change.
- **Removed codes** are a major-version change, with one narrow exception for retiring a code ([overview](https://openwop.dev/spec/v2/core/overview.html) §0a). A registry row can carry a `deprecated` marker.

## What this page is not

This is not the normative source. The error envelope shape is defined in [`core/errors.md`](https://openwop.dev/spec/v2/core/errors.html); each code's preconditions, the events it pairs with (`envelope.retry.exhausted`, `cap.breached`, etc.), and any SR-1 redaction rules are documented in the source named in its "Defined in" column. When this page disagrees with the spec, the spec wins.

This page exists as a reference card for client implementers — one place to grep when wiring error handling.