Docs / Reference
Version mismatch
Return unsupported_protocol_version when host and caller cannot agree on protocol or capability compatibility.
Plain English
This failure mode should return a structured protocol record with unsupported_protocol_version, not an ambiguous framework or transport failure.
Why it exists
Independent callers need to branch on predictable protocol outcomes when a capability cannot safely execute.
Formal definition
A failure mode is a first-class protocol outcome with a stable denial.code or error.code, message, optional details, and evidence semantics.
Concrete example
Ground the concept before the schema.
The caller requests protocol_version 0.2 but the host only supports 0.1.
{ "invocation_id": "inv_version_001", "capability_id": "schedule_technician", "capability_version": "1.0.0", "correlation": { "correlation_id": "case-version" }, "outcome": "denied", "success": false, "data": null, "error": null, "denial": { "code": "unsupported_protocol_version", "message": "Host supports CHP 0.1; caller requested 0.2.", "retryable": false, "details": { "supported": ["0.1"], "requested": "0.2" } }, "evidence_ids": ["evt_version_denied"], "started_at": null, "completed_at": "2026-06-16T15:14:22.104Z"}Developer reference
Version mismatch outcome contract
Use this as the minimum machine-readable shape for tests and independent callers.
The caller requests protocol_version 0.2 but the host only supports 0.1.
Host supports CHP 0.1; caller requested 0.2.
Evidence type or absence expected for this failure.
Relationships
Where this sits in the protocol.
Each concept should explain its neighbors so implementation teams can preserve the boundary across manifests, invocation, evidence, and tests.
Failure outcomes are produced during discovery, validation, authorization, lifecycle checks, execution, or timeout handling.
Evidence should record the decision path when an invocation reaches the host boundary.
Conformance should include both this failure and the neighboring happy path.
Visual model
- 01Caller sends or discovers a protocol surface.
- 02Host or infrastructure detects the failure condition.
- 03Caller receives unsupported_protocol_version with structured details.
Implementation notes
- Return a stable code that callers can match programmatically.
- Include a human-readable message without depending on it for control flow.
- Attach evidence when the host boundary received and evaluated the request.
Common mistakes
- Throwing a raw exception instead of a protocol outcome.
- Using different codes for the same failure across hosts.
- Omitting evidence for denied or rejected requests that reached policy or lifecycle checks.
Related concepts