Block responses & exit codes

When the gateway refuses a request it returns HTTP 403 with an OpenAI-shaped error body. That shape is the point: an OpenAI SDK raises it as an ordinary permission error, so a policy refusal lands in error handling you already have rather than in a code path nobody wrote.

{
  "error": {
    "message": "request blocked by AI firewall policy: guardrail 'No connection strings' matched",
    "type": "policy_violation",
    "code": "request_blocked",
    "blocked_by": "No connection strings",
    "violations": [
      {"policy_uuid": "…", "policy_name": "No connection strings", "rule_type": "blocked_pattern", "action": "block", "detail": "content matched pattern for policy \"No connection strings\""}
    ]
  }
}

type is always policy_violation. code says which stage refused it. blocked_by names the rule that refused the request, and violations lists every rule that matched, including redact and flag rules that fired before it. It never includes the matched text. An Anthropic-dialect route returns the same fields inside Anthropic’s {"type":"error","error":{"type":"permission_error",…}} envelope.

Codes

401 versus 403

A 403 means you authenticated fine and policy said no. A 401 means the gateway does not know who you are — and the usual cause is the two-key confusion:

• The client is sending its provider key. The gateway wants your Vulnetix key; the provider key is the one it holds server-side.
• The key is sent in neither header the gateway reads. It accepts Authorization: Bearer first, then x-api-key, so ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN both work, as long as the value is the Vulnetix key.

vulnetix ai-firewall status checks for both.

Redaction and flagging do not fail

Only --action block produces a 403. The other two actions let the request through:

• redact rewrites each match to the literal [REDACTED] and forwards the request. The model sees the redacted prompt. Your code sees a normal 200 carrying X-Vulnetix-Firewall-Decision: redact.
• flag forwards the request untouched and records that a rule matched. Your code sees a normal 200 carrying X-Vulnetix-Firewall-Decision: flag, and the match shows up in the inference log.

The body never says a rule fired; the response headers do. A client that reads them, as Belai does, can show the user that a redaction or flag happened without the gateway revealing what it matched.

Response headers

Every response the gateway answers reports what it did. The values are facts: a decision, rule names, counts and an id. They never include the text a rule matched, and a provider cannot set them, because the gateway drops any X-Vulnetix-* header from the upstream response.

HTTP/1.1 200 OK
X-Vulnetix-Firewall-Request-Id: 6f1c2d0e-8a4b-4c1e-9f3a-2b7d5e6a9c10
X-Vulnetix-Firewall-Decision: redact
X-Vulnetix-Firewall-Rules: PII%20emails
X-Vulnetix-Firewall-Redactions: 1

On a stream the headers arrive before the first token.

Streaming

A request refused by policy is refused before the stream opens, so you get a plain 403 with the JSON body above — not a stream that opens and then dies, and not a partial completion. Streaming error handling does not need a special case.

CLI exit codes

Commands that gate in CI:

vulnetix ai-firewall status --strict                    # non-zero on any error-level check
vulnetix ai-firewall apply --dry-run --baseline-required   # non-zero if the baseline is unavailable