Block Reason Headers

When Pipelock blocks a request on an HTTP-capable path, it sets a small set of response headers naming the rule class that fired, the severity, and an optional retry hint. The headers let an agent react to a block intelligently without parsing English error pages.

The schema is locked at v1. Additive changes (new reason codes, new optional headers) keep v1.

Headers emitted

The version header lets a future v2 schema break compatibility cleanly. Receivers should parse the version header first and reject unknown majors.

The receipt header is reserved in v2.4. The schema and validator (WithReceipt) ship with this release; production block paths leave the value unset until the receipt-pointer wiring lands. When populated, the value is a 26-character Crockford-base32 ULID identifying an action receipt.

Reason vocabulary

Block reasons are grouped by layer. Values are stable strings; agents can switch on them without parsing English.

Egress and network

Content and payload

MCP and tool

Posture and runtime

Generic

Severity

Three values: info, warn, critical. Severity is hardcoded per reason. Operators control external sink thresholds (emit.webhook.min_severity, emit.syslog.min_severity, emit.otlp.min_severity), not the severity itself, so misconfiguration cannot downgrade a critical event.

Retry hints

Three values:

• none: the block is permanent for this request as is. Retrying the same payload will block again. Examples: dlp_match, ssrf_private_ip, tool_policy_deny.
• transient: the block is environmental and time-bound. Retry with backoff is appropriate. Examples: rate_limit, airlock_active, timeout.
• policy: the block requires an operator to change pipelock policy before a retry can succeed. Examples: kill_switch_active, authority_mismatch.

Agents should switch on the retry hint, not the reason code. New reason codes can ship in any v1.x release; the hint vocabulary is bounded.

Transports

The header is set on every HTTP-capable block path. MCP stdio blocks happen at the JSON-RPC layer; the same reason vocabulary appears in the JSON-RPC error metadata instead.

WebSocket close-frame payloads have a 123-byte limit. When the bare {block_reason: <code>} payload would exceed that, Pipelock substitutes the dedicated block_reason_overflow sentinel rather than truncating the code mid-string.

Two reason codes intentionally have no HTTP header emit site: tool_poisoning (fires on tools/list responses) and tool_chain_blocked (fires on tools/call sequences). Both surface as JSON-RPC errors with the same fixed reason vocabulary. A static production-path matrix gate fails the build if any new reason code ships without at least one production emit site or a documented exemption, so the vocabulary cannot drift from shipped behavior.

Privacy: what the headers do not carry

The header validators reject any value not in the fixed vocabulary or the documented ID format. The headers therefore cannot carry:

• Matched secret content (DLP would defeat itself).
• Specific DLP pattern names (an attacker probing patterns gets dlp_match, not the rule name).
• Agent identifiers, session IDs, or tenant IDs.
• Free-form error messages.

Privacy is enforced at validation, not by convention.

Agent integration pattern

A simple Python wrapper:

import requests
import time

resp = requests.get(target, proxies={"https": "http://pipelock:8888"})

if resp.status_code == 403:
    reason = resp.headers.get("X-Pipelock-Block-Reason", "")
    retry  = resp.headers.get("X-Pipelock-Block-Reason-Retry", "policy")

    if retry == "transient":
        time.sleep(backoff)
        # retry the request
    elif retry == "none":
        raise PolicyDenied(reason)
    else:  # policy: operator action required
        notify_operator(reason)
        raise PolicyDenied(reason)

The agent does not need to enumerate reason codes. The retry hint plus a generic block handler covers every case. New reason codes are forward-compatible because the retry vocabulary is bounded.

Versioning policy

• Additive changes (new reason codes, new optional headers) keep version: 1.
• Removing a reason code, changing the meaning of an existing severity or retry value, or renaming a header bumps the major version.
• Removing the version header bumps the major version.

Receivers that handle unknown reason codes by falling back to the retry hint are forward-compatible across all v1 releases.

See also

• Pipelock v2.4 upgrade guide
• Pipelock v2.4.0 release notes
• Mediation envelope signing for envelope_verify_failed and outbound_envelope_failed
• Action receipt spec for the receipt referenced by X-Pipelock-Block-Reason-Receipt
• Learn-and-Lock agent contracts for contract-aware blocks