Errors

Status: Stable · v2.1.0 (2026-09-11) · RFC 0171 §B.

Why this exists

Every error a v2 host returns is a row in one registry. A client routes on error, never on message, and a code that is not registered is not a protocol error. The registry is the single source for the envelope schema, the HTTP status, and retriability.

The registry

spec/v2/errors.json holds one row per code: { code, httpStatus, retriable, details, since, deprecated? } plus the provenance fields statusSource and source. It registers 96 codes. schemas/v2/error-envelope.schema.json is GENERATED from it and MUST NOT be edited by hand.

A host MUST return a registered code, or a vendor code, in every error response. A vendor code MUST match ^(?!openwop\.)[a-z][a-z0-9](-[a-z0-9]+)\.[a-z][a-z0-9_]*$ with its first segment an org registered in spec/v2/declaration.json; openwop. is reserved. The registry grows by the closed-enum rule in overview.md §0: a producer MUST NOT emit an unregistered member, and a consumer MUST accept an unknown registered member and MUST NOT act on it.

The envelope

Every error response body MUST be { error, message, details? } and nothing else (additionalProperties: false). error is the registered code or a vendor code; message is a non-empty string; details is an object whose shape is the row's details schema. A row whose details is null accepts any object; when a row registers a schema, the generated envelope becomes a oneOf discriminated on error. Contextual data (conflict refs, trace ids, validation paths) MUST live under details, never at a new top level. The same envelope is the per-id error of bulkCancelRuns (runs.md). When present, details.correlationId MUST be a non-empty string.

x-openwop-http-status and x-openwop-retriable in the generated schema mirror the registry; a host MUST answer with the registered status.

Retry timing

Retry timing lives in the Retry-After header only. details.retryAfter, details.retryAfterMs and details.retryAfterSeconds are not part of v2 and a host MUST NOT emit them. A 429 rate_limited response MUST set Retry-After. The retriable rows are residency_unavailable, rate_limited, internal_error, pack_registry_unreachable, runner_unavailable.

One code per state

An interrupt has one code per state: a token or run-scoped resolve against an interrupt that is already resolved, or whose run is cancelled or completed, MUST return 409 interrupt_already_resolved; a signed token past its expiresAt MUST return 410 interrupt_expired; a token whose alg or kid the host does not accept MUST return 401 interrupt_token_invalid (see interrupt.md, identity.md). The idempotency mismatch code is idempotency_key_mismatch only (idempotency.md).

Codes by HTTP status

Generated from spec/v2/errors.json (97 codes; retriable and statusSource are in the registry).