# Failure code catalogue

**Source availability:** This checkout includes qualified changes made after the published `v0.7.0` release. Package labels still read .NET `0.7.0` and Python/TypeScript `0.3.0`; those labels do not make locally rebuilt artifacts identical to the published downloads. Structured `PluginFailure` details, `DetailedFailureSink`, event 1008 and combined primary/cleanup error metadata describe current source, not the original published packages. Use the matching release tag for a published-package integration; see [current status](https://weaveport.dev/docs/status.md).

Use `Failure.Code` for structured failure identity when present, and the existing status otherwise. Codes identify categories; none guarantees that an external action did not execute. Retain `MayHaveExecuted` and apply an application-owned idempotency or compensation policy before retrying.

| Code | Meaning |
| --- | --- |
| `ok` | Successful legacy status; not a failure code. |
| `failed` | Worker/channel I/O failed or an older peer supplied no detailed code. |
| `sdk-error` | Author handler or callback processing failed. |
| `cleanup-error` | Owned SDK resources could not be released cleanly. |
| `protocol-error` | An explicitly validated protocol boundary rejected malformed input. |
| `internal-error` | Unexpected host state or cancellation without a requested owned token. |
| `cancelled` | Caller cancellation or remote cancellation status. |
| `timeout` | An owned operation/startup/exchange deadline expired, or gRPC reported deadline exceeded. |
| `disabled` | Host/plugin lifetime ended or shared recovery is disabled. |
| `denied` | Callback authority or transport permission refused. |
| `busy` | Admission capacity is unavailable before dispatch. |
| `version-mismatch` | Advertised artifact version differs from the configured version. |
| `input-limit` | Unary request exceeds the contract limit. |
| `value-limit` | Unary response exceeds the contract limit. |
| `stream-limit` | Stream item or total size exceeds the contract limit. |
| `chunk-limit` | Binary source chunk size is outside the contract. |
| `source-unsupported` | The bound client does not support binary sources. |
| `invalid-mode` | Gateway request mode is unsupported. |
| `callback-failed` | Shared host callback processing failed. |
| `binding-denied` | Gateway binding authentication failed. |
| `gateway-failed` | Gateway internal failure or transport data loss. |
| `unavailable` | Remote transport is unavailable. |
| `resource-exhausted` | Remote transport reported capacity exhaustion. |
| `invalid-argument` | Remote transport rejected arguments. |
| `not-found` | Remote transport could not find the requested resource. |
| `unimplemented` | Remote transport does not implement the requested operation. |
| `unknown-error` | Unknown external failure category; descriptions are never parsed as codes. |

`CleanupFailed` records an additional cleanup failure without overwriting the primary code. Phase is `prepare`, `exchange` or `transport`; correlation is an opaque invocation identifier. Old peers may supply neither phase nor correlation. Raw plugin exception details are not sent across the protocol. See [diagnostics](https://weaveport.dev/docs/runtime-diagnostics.md) for local opt-in exception delivery.

The [shared contract](https://raw.githubusercontent.com/yesbert/WeavePort/main/contracts/protocol.json) owns stable wire vocabulary and interoperability limits. Unary values are bounded at 512 KiB; frames at 1 MiB; stream items at 128 KiB; batches at 16 items and 256 KiB; stream totals at 64 MiB. Source requests use 4–256 KiB chunks, defaulting to 64 KiB. These limits bound protocol buffering and preserve interoperable behavior; they are not operating-system memory limits. Concurrency configuration is bounded at 1024 calls. Component-local buffering, retained identity windows and timing policies have separate names and ownership.