Error codes

The canonical OpenWOP error envelope is { code, message, details? } returned with the appropriate HTTP status. This page lists every code in the v2 error registry with its HTTP status, a one-line meaning, and the spec section that carries the normative definition.

Generated from spec/v2/errors.json at build time, so it cannot drift from the corpus. Envelope shape: core/errors.md.

Envelope shape

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

• code — machine-readable identifier. Stable within a major; new codes land additively.
• message — human-readable explanation. MUST NOT include the offending input verbatim when that input could echo a prompt-injection payload or a credential.
• details — optional structured context. Documented per code below.

The HTTP status code carries the primary classification; the code field disambiguates within the status class.

Codes by HTTP status

HTTP 400 — 26 codes

HTTP 401 — 10 codes

HTTP 403 — 11 codes

HTTP 404 — 6 codes

HTTP 406 — 1 code

HTTP 409 — 14 codes

HTTP 410 — 2 codes

HTTP 413 — 2 codes

HTTP 415 — 1 code

HTTP 422 — 16 codes

HTTP 426 — 1 code

HTTP 429 — 1 code

HTTP 500 — 3 codes

HTTP 501 — 1 code

HTTP 503 — 2 codes

_97 codes, generated from spec/v2/errors.json at build time._

Stability guarantees

Per Versioning & compatibility:

• New codes land additively within a major. Clients that match an unknown code against a known set MUST treat it as the parent HTTP status family.
• Existing codes never change their HTTP status mapping or their semantic meaning within a major. A code's details shape may gain new optional fields.
• Removed codes never happen within a major. A code that turns out to be redundant is documented as superseded; the old code keeps working.

What this page is not

This is not the normative source. The error envelope shape is defined in core/errors.md; 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 spec section linked above. 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.