OpenWOP — Error codes

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

Envelope shape

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

HTTP 400 — 28 codes

Code	Meaning	Retriable
`connection_provider_unresolved`	A connector or pack references a connection provider that nothing defines.	no
`connector_action_unresolved`	A pack's connector action or trigger names a node type the same manifest does not define.	no
`credential_scope_unsupported`	The credential request names a scope the host does not support.	no
`delegation_chain_cyclic`	The delegation chain repeats a subject.	no
`delegation_chain_too_long`	The delegation chain is longer than the host's bound.	no
`idempotency_key_invalid`	The Idempotency-Key value does not match the required grammar.	no
`interop_version_unsupported`	An A2A or MCP negotiation would land below the host's advertised minimum version.	no
`oauth_provider_unsupported`	A node names an OAuth provider the host does not advertise.	no
`oauth_scope_unsupported`	A node asks for an OAuth scope the provider does not advertise.	no
`pack_dependency_cycle`	The pack dependency graph contains a cycle.	no
`pack_engine_unsupported`	The pack's engines range does not admit the host's protocol major.	no
`pack_integrity_failure`	The uploaded or fetched pack's SHA-256 does not match the declared digest.	no
`pack_kind_invalid`	The manifest's content does not match its declared pack kind, or mixes kinds.	no
`pack_lockfile_incomplete`	The workspace references a pack the lockfile does not list.	no
`pack_peer_dependency_missing`	The host does not provide a capability the pack declares as a peer dependency.	no
`pack_peer_dependency_undefined`	A peer-dependency key is not a declared capability family or alias.	no
`pack_signature_invalid`	The pack's signature, signing key or namespace check failed.	no
`pack_validation_failed`	The pack manifest is invalid.	no
`protocol_version_mismatch`	A /v1/ path was called with an OpenWOP-Version other than 1.	no
`schedule_horizon_exceeded`	A schedule asks for a fire time beyond the host's advertised horizon.	no
`sub_chain_cycle`	A workflow chain transitively composes itself.	no
`sub_chain_depth_exceeded`	Workflow chain nesting is deeper than the host's advertised maximum.	no
`unsupported_runtime`	The host cannot execute the pack's runtime language.	no
`unsupported_stream_mode`	The requested stream mode is malformed or not served; details.supported lists the modes the host serves.	no
`until_in_past`	A capability record's until date is in the past.	no
`validation_error`	The request is malformed or fails schema validation.	no
`webhook_endpoint_unverified`	The webhook endpoint did not answer the verification challenge; nothing was stored.	no
`webhook_url_rejected`	The webhook URL is not an allowed public https:// destination.	no

HTTP 401 — 12 codes

Code	Meaning	Retriable
`audience_mismatch`	The credential was issued for a different audience than this host.	no
`connector_auth_declined`	The user declined the connector's authorization request, so the node failed.	no
`connector_auth_expired`	The connector's credential expired and could not be refreshed, so the node failed.	no
`credential_lifetime_exceeded`	The credential's lifetime exceeds the bound the host advertises for its lane, or it carries no iat.	no
`credential_revoked`	The presented API key or session has been revoked.	no
`delegation_expired`	A delegation or workload credential is past its lifetime.	no
`identity_unresolvable`	The credential verified, but it maps to no known subject.	no
`identity_unverified`	The credential or delegation chain failed verification.	no
`interrupt_token_invalid`	The interrupt token uses an algorithm or key the host does not accept.	no
`key_revoked`	The API key has been revoked or its subject disabled.	no
`sender_constraint_missing`	The request does not meet the lane's minimum sender-constraint assurance.	no
`unauthenticated`	No credential was sent, or the credential is invalid.	no

HTTP 403 — 13 codes

Code	Meaning	Retriable
`credential_forbidden`	The credential exists but is outside the caller's scope.	no
`credential_scope_forbidden`	The credential cannot be bound at the requested scope.	no
`delegation_scope_amplified`	A delegated link claims more scope than its delegator holds.	no
`egress_denied`	The host refused an outbound request a pack asked it to make: the address guard or the egress policy denied it.	no
`forbidden`	The caller is authenticated but not permitted to do this.	no
`force_engine_version_forbidden`	Forcing an engine version is refused outside test keys.	no
`id_tenant_mismatch`	The id's tenant segment is not the caller's tenant.	no
`mock_provider_forbidden`	The mock AI provider is refused outside test keys.	no
`pack_namespace_unauthorized`	The pack's signing key is not allowed for its namespace.	no
`run_forbidden`	The caller may not act on this run.	no
`sandbox_capability_denied`	Sandboxed code called a host capability it is not allowed to use.	no
`sandbox_escape_attempt`	Sandboxed code tried to escape its sandbox.	no
`workspace_membership_required`	The caller is not a member of the workspace the request names.	no

HTTP 404 — 6 codes

Code	Meaning	Retriable
`credential_not_found`	No credential resolves for the requested reference.	no
`interrupt_not_found`	The interrupt does not exist.	no
`not_found`	The resource does not exist, or the caller may not see it.	no
`pack_version_not_found`	The requested pack version is not served.	no
`replay_source_missing`	During replay, a side-effecting node has no recorded source outcome, so it failed closed.	no
`signature_not_available`	No signature is served for this pack version.	no

HTTP 406 — 1 code

Code	Meaning	Retriable
`protocol_version_unsupported`	The OpenWOP-Version header names a version the host does not list; details.protocolVersions lists what it serves.	no

HTTP 409 — 15 codes

Code	Meaning	Retriable
`connection_provider_conflict`	Two registrations claim the same connection provider id.	no
`envelope_correlation_conflict`	An envelope reuses a correlationId already seen in this run with a different type.	no
`idempotency_in_flight`	A request with the same idempotency key is still being processed.	no
`idempotency_key_mismatch`	The idempotency key was reused with a different request.	no
`interrupt_already_resolved`	The interrupt is already resolved, its run has ended, or its token was invalidated.	no
`pack_dependency_conflict`	Two packs require versions of a third pack that no single version satisfies.	no
`pack_integrity_mismatch`	The fetched pack's SHA-256 does not match the lockfile.	no
`replay_context_summary_unavailable`	The fork was refused: the host cannot serve the context summary as of the fork point.	no
`replay_diverged_at_refusal`	Replay diverged: the source and the replay disagree on whether the AI provider refused.	no
`replay_memory_snapshot_unavailable`	The fork was refused: the host cannot serve memory state as of the fork point.	no
`run_already_active`	A run for the same scope is already active and deduplication is enforced.	no
`run_state_conflict`	The run's current status does not allow this transition; details.runStatus names it.	no
`run_terminal`	The run has already finished, so it cannot be changed.	no
`version_conflict`	This pack version was already published with different content.	no
`workspace_conflict`	The workspace file changed since the caller last read it.	no

HTTP 410 — 3 codes

Code	Meaning	Retriable
`interrupt_cancelled`	The interrupt was cancelled. The core resolve operations never return this code.	no
`interrupt_expired`	The interrupt token is past its expiry.	no
`run_expired`	The run, or the part of its event log the request needs, was purged under the host's documented retention.	no

HTTP 413 — 2 codes

Code	Meaning	Retriable
`payload_too_large`	The request body is larger than the host accepts.	no
`workspace_too_large`	The workspace file is larger than the host's advertised maximum.	no

HTTP 415 — 1 code

Code	Meaning	Retriable
`unsupported_media_type`	The request body's Content-Type is not accepted.	no

HTTP 422 — 27 codes

Code	Meaning	Retriable
`approval_rejected`	An approval gate resolved rejected (a decision, a quorum or a timeout) and no edge routed the failure, so the node and the run failed.	no
`budget_exhausted`	A hard budget dimension was exhausted and the run failed.	no
`budget_model_denied`	The run's resolved model is outside its budget's `modelAllow`, or inside its `modelDeny`, so it was refused before the call.	no
`capability_not_provided`	The host does not provide a capability the request or pack requires, including a node type it cannot execute.	no
`capability_required`	The workflow uses a node type whose capability the host does not advertise.	no
`connection_auth_metadata_mismatch`	The provider's discovered issuer or endpoint differs from the one the manifest or registration pinned.	no
`credential_required`	A node needs a credential that did not resolve.	no
`envelope_invalid`	An AI envelope failed validation and was refused.	no
`envelope_refusal`	The AI provider explicitly refused; the host does not retry.	no
`envelope_truncation_unrecoverable`	The AI output stayed truncated after the retry budget ran out, so the node failed.	no
`eval_gate_unmet`	A deployment transition was refused because the eval run its gate requires is not terminal and passing.	no
`fork_point_invalid`	The fork point is not a valid sequence in the source run's log.	no
`loop_limit_exceeded`	A loop exceeded its iteration limit.	no
`mcp_mrtr_rounds_exceeded`	An MCP exchange asked for more tool-result rounds than the host's advertised ceiling.	no
`node_config_invalid`	A node's configuration is missing a required value or holds one the node cannot use, so the node failed.	no
`pack_runtime_requirement_unmet`	The host does not meet a runtime requirement the pack declares.	no
`provider_policy_denied`	Host provider policy refused the model or provider before the call, so the node failed.	no
`recursion_limit_exceeded`	The run hit its recursion safety cap.	no
`residency_unavailable`	The host cannot serve the requested data-residency region.	yes
`run_timeout`	The run exceeded its time limit and failed.	no
`sandbox_invocation_error`	A pack node running in the sandbox threw an error outside the canonical sandbox catalog, so the node failed.	no
`sandbox_memory_exceeded`	Sandboxed code exceeded its memory limit.	no
`sandbox_timeout`	Sandboxed code exceeded its wall-clock limit.	no
`storage_limit_exceeded`	A storage call was refused because it would exceed an advertised limit or the tenant's quota.	no
`token_budget_exceeded`	A memory distillation could not be completed within its effective token budget, so the run failed and wrote no partial archive.	no
`unknown_envelope_kind`	The envelope's type is neither universal nor in the host's supported catalog.	no
`unknown_schema_version`	The envelope's schemaVersion is above the version the host advertises for that kind.	no

HTTP 426 — 1 code

Code	Meaning	Retriable
`client_version_unsupported`	The client is below the host's advertised minClientVersion; details.minClientVersion, when present, names the floor.	no

HTTP 429 — 1 code

Code	Meaning	Retriable
`rate_limited`	Too many requests. Retry after the Retry-After header.	yes

HTTP 500 — 4 codes

Code	Meaning	Retriable
`event_type_unmapped`	The run's event log holds an event type the host cannot translate, so the log is unreadable.	no
`internal_error`	The host failed unexpectedly.	yes
`pack_load_failure`	The pack could not be loaded when the workflow was registered.	no
`payload_unprojectable`	An event payload cannot be represented under the requested contract. Never retried.	no

HTTP 501 — 1 code

Code	Meaning	Retriable
`credential_unavailable`	The host cannot resolve credentials at all, so the run cannot proceed.	no

HTTP 502 — 2 codes

Code	Meaning	Retriable
`mcp_error`	An MCP server the host called answered with a JSON-RPC error, so the node failed.	no
`upstream_unavailable`	A host service could not reach the upstream it depends on (a fetch target, an MCP server, a queue backend), so the call failed.	yes

HTTP 503 — 3 codes

Code	Meaning	Retriable
`pack_registry_unreachable`	The pack registry could not be reached.	yes
`runner_unavailable`	No runner is available to execute this run.	yes
`service_unavailable`	The host is at capacity. Retry after the `Retry-After` header when present.	yes

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

Stability guarantees

Per Versioning & compatibility:

New codes land additively within a major. A client MUST accept an unknown code and MUST NOT act on it (overview.md §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 §0a). A registry row can carry a deprecated marker.

Route on `error`, never on message.

Codes by HTTP status

The envelope

Every code

Envelope shape

Codes by HTTP status

HTTP 400 — 28 codes

HTTP 401 — 12 codes

HTTP 403 — 13 codes

HTTP 404 — 6 codes

HTTP 406 — 1 code

HTTP 409 — 15 codes

HTTP 410 — 3 codes

HTTP 413 — 2 codes

HTTP 415 — 1 code

HTTP 422 — 27 codes

HTTP 426 — 1 code

HTTP 429 — 1 code

HTTP 500 — 4 codes

HTTP 501 — 1 code

HTTP 502 — 2 codes

HTTP 503 — 3 codes

Stability guarantees

The spec wins.