GuardrailBlockedError.
Enabling guardrails
Passguardrails: true (guardrails=True in Python) to any wrapper to enable both pre- and post-LLM checks with default settings.
GuardrailBlockedError is thrown before the LLM call is made (pre) or before the result is returned (post).
In TypeScript,
wrapOpenAI() returns a wrapped client instance you call directly. In Python, patch_openai() monkey-patches the openai module in place — import openai (or construct openai.OpenAI()) after calling patch_openai(), then call it exactly as you would unpatched.On by default
You do not have to passguardrails for tool calls to be checked. In the integrations that see tool calls, leaving the option unset runs tool-only checks: before a tool runs, Zespan checks the call (tool name, arguments and the earlier calls in the trace) against your rules, with no text sent.
- No rules, no cost. When a check finds the project has no enabled rules, the SDK skips further checks for 60 seconds and the result carries
skipped: "no_rules". The check endpoint says this withnoRules: truein its reply (see the API reference). Add a rule and checks start within a minute. - No tool rules, no tool checks. A project that has rules but only ones that read reply text (PII, toxicity, regex and the like) can never block a tool call. For a tool-only check the endpoint then replies
noToolRules: true, and the SDK skips tool-only checks for 60 seconds (the result carriesskipped: "no_tool_rules"). Text checks are not affected. An enabled template counts as a tool rule. - Fail-open by default. If the check is slow or fails, the tool runs. The tool-only default waits at most 300 ms for each check, in every integration that checks tool calls. If one check in a reply times out or fails, the SDK skips the remaining checks of that reply, so a slow Zespan never adds a delay per tool call. Passing
guardrails=True(true) keeps the client default of 5 seconds. Setfail_closed(failClosed) totrueto block instead. On the Google ADK before-tool path the blocked call gets the reasonguardrail_unavailable, and the span carrieszespan.guardrail.unavailable: truewhen the check could not be answered. The other wrappers record the failed check as an errorguardrailspan, but do not mark the model span. - Each check adds a guardrail span, which counts toward your event quota (see Guardrail spans).
Fine-grained configuration
Pass a configuration object instead oftrue/True to control exactly which phases run and how errors in the guardrail service are handled.
When
true, runs a content check on the prompt before the LLM call is made. A block at this phase prevents the LLM from ever receiving the prompt.When
true, runs a content check on the completion before it is returned to your application. A block at this phase prevents unsafe completions from reaching users.Controls behavior when the guardrail service itself returns an error (e.g. network timeout, service unavailable). Named
fail_closed in Python.false(default): errors from the guardrail service are swallowed and the LLM call proceeds normally.true: errors from the guardrail service are re-thrown, blocking the LLM call. Use this in high-risk applications where you prefer to fail safe.
Handling GuardrailBlockedError
When a guardrail policy blocks content, the SDK throws (Python: raises) a GuardrailBlockedError. Catch it to handle the block gracefully — for example, by returning a fallback response to the user.
Python SDK before the October 2026 release: guardrail checks from Python went to a URL without the
/v1 prefix and got a 404, so with the default fail_closed=False every check was silently skipped and the call went through (with fail_closed=True every guarded call raised). Upgrading makes the checks run for real: a rule whose action is block (or a policy applied at deny) now raises GuardrailBlockedError from Python, and each guarded call waits for the check, bounded by its timeout (5 seconds by default). Rules at warn or log, and policies at dryrun or warn, only record. If you turned guardrails on in Python earlier, review your enabled rules before upgrading, or set them to warn first. A check that errors or times out still lets the call through unless you set fail_closed=True.GuardrailBlockedError properties
Both SDKs expose the same two attributes on the error instance.
Array (Python: list) of results from individual guardrail policies that ran. Each result describes what the guardrail found and what action it took.
GuardrailResult fields
Each entry in error.results represents one guardrail policy evaluation:
Unique identifier of the guardrail policy that produced this result. Named
guardrail_slug in Python.What the guardrail did. One of
"allowed", "blocked", "redacted", or "warned"."allowed"— content passed without modification"blocked"— content was rejected;GuardrailBlockedErroris thrown"redacted"— sensitive content was removed and the modified text is used instead"warned"— content was flagged but allowed through
Human-readable explanation of why this guardrail triggered, or
null (Python: None) if it did not trigger.The redacted version of the text, or
null (Python: None) if no modification was made. When a guardrail redacts content, the modified text is used in place of the original for the LLM call or returned response. Named modified_text in Python.Guardrails on other wrappers
Guardrails work on all provider wrappers. Pass the sameguardrails option to wrapAnthropic, wrapGoogle, wrapGoogleGenAI, wrapOpenRouter, wrapBedrock, wrapMistral, wrapLiteLLM, or the LangChain callback handler.
guardrails keyword argument on patch_anthropic, patch_google, patch_google_genai, patch_bedrock, patch_mistral, patch_litellm, and patch_groq.
If you trace multi-agent workflows with
withAgent, the agent name and its recent tool calls are automatically included in every guardrail check made inside that block — no extra wiring needed. This lets agent-specific guardrail policies (agent rate limiting, tool misuse, loop detection, scope enforcement, delegation control) evaluate agent behavior alongside standard content checks.Both SDKs send the tool the model asked for, its arguments and the earlier tool calls of the trace with the check made after the model replies, including when the reply is only tool calls (one check per call).Calling guardrails directly
Theguardrails wrapper option only checks content that flows through an LLM wrapper call. Sometimes you need to gate something that isn’t an LLM call at all — a RAG retrieval step before it’s fed into a prompt, a tool result, or any other non-LLM action. For that, call the guardrail check directly instead of going through a wrapper.
Unlike the wrapper-level flow, this direct call never throws
GuardrailBlockedError itself — it always resolves to a response object. Check allowed (result.allowed in TypeScript, result["allowed"] in Python) yourself and decide what to do: skip the step, raise your own error, log and continue, and so on.Input fields
Which phase this check represents. Purely descriptive at the call site — it’s passed straight through to whichever guardrail policies key off phase, and shows up in guardrail event logs.
The trace this check is associated with, for correlating the guardrail event with the rest of the trace in the dashboard. Named
trace_id in Python.The model this check relates to, if any. Some guardrail policies scope their rules to specific models.
A label for what kind of call this is (e.g.
"rag-retrieval", "chat"). Lets you scope guardrail policies to specific operations.Estimated cost in USD of the operation being checked, in case a guardrail policy enforces a per-call cost ceiling. Named
estimated_cost in Python.Token count of the input being checked, in case a guardrail policy enforces a token limit. Named
input_tokens in Python.Name of the agent making this call, for agent-scoped policies (agent rate limiting, scope enforcement, delegation control). Named
agent_name in Python.Name of the tool being invoked, for tool-misuse and delegation-control policies that allowlist/blocklist specific tools. Named
tool_name in Python.The tool call being checked: its name and its arguments, for policies that look at what a tool is about to do (for example the amount of a payment). Named
current_tool_call in Python, which takes a dict {"name": ..., "args": {...}}.Recent tool calls in this trace, used by loop-detection and tool-misuse policies to spot repeated or excessive calls. Named
recent_tool_calls in Python, which takes a list of dicts with the same keys (toolName, args). Pass the calls made before the current one and set recentExcludesCurrent (recent_excludes_current) to true, so repeat limits count the current call once.Set to
true when recentToolCalls does not include currentToolCall. Named recent_excludes_current in Python.Set to
true when the check is for a tool call only, with no text to judge. Named tool_call_only in Python. A tool-call-only check runs post and both rules, and pre rules only when they judge a single tool call (loop_detection, scope_enforcement, require_confirmation, tool_misuse, and schema_contract on tool_args), so a policy drafted for post still applies to a tool call checked before it runs. Request-level pre rules (agent_rate_limit, cost_ceiling, model_governance, delegation_control) are not run, and spend no rate-limit counts, once per tool call.Python only. When the guardrail service request itself fails (network error, timeout, non-2xx response),
fail_open=True (default) swallows the error and returns {"allowed": True, "results": [], "modifiedText": None}. Set fail_open=False to re-raise the underlying exception instead.Response shape
Both languages return the same three top-level fields:allowed (boolean), results (an array/list of per-policy results), and modifiedText — the redacted text, or null/None if nothing was modified. When the project has no enabled rules, the SDK result also has skipped: "no_rules" and later checks are skipped for 60 seconds (see On by default).
Guardrail spans
Every check, direct or from a wrapper or integration, is recorded as aguardrail span under the span it checked, with the check’s latency and status and two metadata keys: zespan.guardrail.action (allowed, warned, redacted or blocked: the strictest action any rule took) and zespan.guardrail.slugs (the rules that fired). The span holds no checked text, no reason and no replacement text. A direct call that names no span (spanId in TypeScript, span_id in Python) checks the current span, so the check appears under the work it guarded. The span never changes the check: a blocked check still throws GuardrailBlockedError, and a check that fails still throws its own error (or, in Python with fail_open=True, returns the allowed fallback and the span is marked as an error).
Each check adds one span, which counts toward your event quota. To stop recording it, set guardrailSpans: false (TypeScript) or guardrail_spans=False (Python) in the SDK options, or set the environment variable ZESPAN_GUARDRAIL_SPANS=off (also false, 0, no). Either one turns it off, it is read at call time, and the check itself is not affected.
Deadline
Each check tells Zespan how long the SDK will wait, using thex-zespan-deadline-ms header set to the check’s timeout (timeoutMs in TypeScript, timeout in Python; 5 seconds by default). Zespan fits its rules into that budget so you get an answer before the SDK gives up. AI rules (such as Semantic Judge) that it had no time to start come back as errored results, handled by their If the check can’t run setting, and their slugs are listed in an optional skippedForDeadline field on the response.
In TypeScript, results is a typed array of GuardrailResult objects using the field names documented above (guardrailSlug, passed, action, reason, modifiedText).
In Python,
zespan.check_guardrails() returns a plain dict — result["allowed"], result["results"], result["modifiedText"] — and each entry in result["results"] is also a raw dict using the same camelCase keys as the wire format (guardrailSlug, passed, action, reason, modifiedText, latencyMs), not the snake_case names used elsewhere in the Python SDK. Use dict-key access (r["guardrailSlug"] or r.get("reason")) when working with the direct API’s response in Python.By design, this differs from GuardrailBlockedError.results (used in the wrapper flow above), where each entry is a GuardrailResult object with snake_case attributes (guardrail_slug, modified_text, etc.).
