Error reference

Errors come back in the dialect of the route you called, never the provider’s. An Anthropic SDK that hits /v1/messages gets an Anthropic-shaped error even when the failure is “this provider is not an Anthropic provider” — because that is the only shape it can render. Given an OpenAI-shaped body, Claude Code would print a bare API Error: 403 with no detail, and every guardrail block would be unreadable.

The two envelopes

{
  "error": {
    "message": "human-readable explanation",
    "type": "policy_violation",
    "code": "request_blocked",
    "blocked_by": "no-secrets",
    "violations": [ ... ]
  }
}

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "code": "request_blocked",
    "message": "human-readable explanation",
    "blocked_by": "no-secrets",
    "violations": [ ... ]
  }
}

Status-to-type mapping for the Anthropic envelope:

401 — authentication

Every one of these means the credential is wrong, not the request.

403 — policy

You are authenticated. Your organisation’s policy refused the request.

A guardrail block carries the detail:

{
  "error": {
    "message": "request blocked by AI firewall policy: content matched pattern for policy \"no-private-keys\"",
    "type": "policy_violation",
    "code": "request_blocked",
    "blocked_by": "no-private-keys",
    "violations": [
      {
        "policy_name": "no-private-keys",
        "rule_type": "blocked_pattern",
        "action": "block",
        "detail": "content matched pattern for policy \"no-private-keys\""
      }
    ]
  }
}

violations names the rules that fired. It never contains the content that triggered them.

404 — routing

unsupported_api is the one you will actually hit, and it is almost always the /v1 asymmetry:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "code": "unsupported_api",
    "message": "provider groq does not support the Anthropic Messages API (POST /v1/messages). Use POST /v1/chat/completions for groq, or point your Anthropic client at a provider that serves the Messages API: https://guardrails.vulnetix.com/anthropic/{orgUuid} (note: no /v1 suffix — the Anthropic SDK appends it)"
  }
}

See base URLs & request surfaces.

400 — your request

413 — too large

request_too_large — the request body exceeds 8 MiB.

This is a transport limit, not a policy. It is not configurable, and it is not a token limit. Coding agents that read large files can hit it.

5xx — us

Errors you will not see

Because these features do not exist: no 429 rate limit, no quota error, no budget-exceeded error, no billing error. The firewall imposes none of these. A 429 relayed to you came from the provider, against your own account and your own quota. See limitations & roadmap.

Handling these in code

The pattern that matters: distinguish your organisation refused this from the provider refused this. Both are HTTP errors, and only the first is something you can fix by changing your prompt.

from openai import OpenAI, APIStatusError

try:
    resp = client.chat.completions.create(model="gpt-4o-mini", messages=[...])
except APIStatusError as e:
    body = e.response.json().get("error", {})
    code = body.get("code")

    if code == "request_blocked":
        print(f"Blocked by your organisation's rule: {body['blocked_by']}")
    elif code in ("model_denied", "model_not_allowed"):
        print("That model is not permitted by your organisation.")
    elif code == "provider_key_missing":
        print("No provider key is stored. Run: vulnetix ai-firewall key set <provider>")
    else:
        raise

Note there is no error for a redaction. A redacted request returns a normal 200. The client cannot tell. See redact PII.

Related

• Troubleshooting — symptom-first.
• Your two keys — the cause of most 401s.
• Base URLs — the cause of every unsupported_api.