Skip to main content

Protect requests with guardrails

Enterprise Tier

A guardrail moves content inspection into the gateway, where project rules run inline on model traffic before a request reaches a provider and again before the response returns. Every integration whose key belongs to a project with active enforce-mode rules inherits that protection without code changes. This is the developer-facing view: which traffic is protected, how to recognise that a guardrail acted, and how to request coverage where it is missing.

Persona: Developer working in the Developer Console.

Estimated time: 10 to 15 minutes to review how guardrails apply to existing traffic and to confirm their effect in Request Logs.

When this guide applies​

Guardrails are relevant whenever request or response content carries risk that should be handled before it crosses an application or provider boundary. The guide is especially useful in these situations:

SituationWhat guardrails address
User-supplied prompts may contain PIIRedaction or blocking before content reaches an external provider
Responses are shown directly to end usersFiltering of unsafe or disallowed content before it returns to the application
A workload must meet a data-handling or compliance requirementA consistent, centrally enforced control rather than per-service logic
An integration must behave identically across multiple providersEnforcement on the gateway applies regardless of which backend serves the request

Where the concern is which backend serves a request rather than what the request contains, Route requests across providers is the relevant guide instead.

Outcomes​

By the end of this guide:

  • The role of a guardrail as an inline, gateway-enforced control is understood, along with the boundary between developer and operator responsibilities.
  • The way guardrails attach to traffic at the project is understood well enough to reason about which requests are protected.
  • A guardrail action can be recognised from the response signals, and the limits of what the Console shows about it are clear.
  • A request for guardrail coverage can be raised with the operator team with enough detail to act on.

Prerequisites​

  • A working API key with recent traffic against it, as set up in Route requests across providers.
  • Familiarity with Request Logs, as covered in Monitor traffic and usage. Request Logs is the Console surface on which a refused request is located.
  • For requesting new coverage: a point of contact on the platform operator team, since guardrails are defined for a project in the Admin Dashboard rather than the Console.

Step 1: understand how a guardrail acts on a request​

A guardrail is evaluated inline by the gateway on the model request path. Two points on that path can be inspected:

  • On the request: before the prompt is forwarded to a provider. A guardrail can redact matched content (for example, masking an email address or an account number) so that the sanitised prompt is what the provider receives, or it can block the request outright so that nothing is forwarded at all.
  • On the response: before the model output returns to the calling application. A guardrail can redact matched content from the response or block the response so that the disallowed content is never delivered.

Standalone MCP profile traffic (/mcp/*) is not inspected by content guardrails. That path is governed by identity, access control, and audit instead.

Rules use check types such as pii, secrets, jailbreak, and toxicity, each scored by a provider (regexp, builtin, tetrate, or another configured engine). The action on a match is redact or block; whether that action is applied is controlled by the rule's mode (enforce or monitor). Thresholds and patterns are operator-configured. From a developer's perspective, the contract is straightforward: a protected request is inspected on the way in and on the way out, and the gateway either passes it through, passes through a redacted version, or refuses it with HTTP 403.

Step 2: know which traffic is protected​

Guardrails are defined by the operator for a project, not chosen per request by the developer. A request is protected because it routes through a project that has active guardrails, not because the application opted in on the call itself. Protection is invisible in the request shape: the model field, the message content, and the headers are unaffected.

This has two practical consequences:

  • Protection follows the project. Every integration whose API key belongs to a project with active enforce-mode rules is subject to those rules. Keys in a different project, or in the same project before any rules are enforced, are not.
  • Coverage can differ between projects. One project may carry a strict PII policy while another, used for an internal experiment, carries none. Naming keys by purpose (as in Monitor traffic and usage) still helps when asking operators which project a key belongs to.

Because the Console does not expose guardrail configuration to developers directly, the reliable way to confirm whether traffic is protected, and by what, is to ask the operator team. The response signals described in Step 3 confirm only that a rule acted, not what rules exist.

Step 3: tell when a guardrail acted on a request​

A guardrail leaves an immediate signal in the response. The durable record of what a rule did is a guardrail-trigger record, which is an operator-side surface rather than a Console one.

Response signals​

  • A redaction is visible in the content itself. Where a guardrail masked matched text, the prompt the provider received, or the response the application received, contains the masked form rather than the original. A request that succeeds with altered content is the normal signature of a redaction guardrail.
  • A block is surfaced as a refusal rather than a model completion. The gateway returns HTTP 403, carrying the guardrail's configured blocked-response message where one is set, and a correlation identifier. Application code that already handles non-success responses from the gateway will surface this in the same path it uses for other errors.

The status code alone separates a guardrail block from the failures it is most often mistaken for: a rate limit returns 429 and an upstream failure returns 5xx, so a 403 on a request that previously succeeded points at content rather than availability, and retrying it changes nothing. Step 5 covers why failover is not the remedy either.

What the Console shows, and what it does not​

Request Logs records the request as the gateway processed it, so it confirms that a request was refused and with what status and message. The columns and detail panel are described in Monitor traffic and usage. For a request suspected of triggering a guardrail:

  1. Open Monitoring → Request Logs in the Console.
  2. Filter by the API key the integration uses and a time range covering the request.
  3. Locate the request and open its detail panel.
  4. Read the status and the error message in the response body.

What Request Logs does not show is which rule fired, the score it returned, or whether the rule was in enforce or monitor mode. That detail lives in the guardrail-trigger record, which the operator team reads. The correlation identifier on the 403 is the value to quote when asking them, because an operator can resolve it to the rules that triggered and the content that caused the block; see Guardrails best practices and FAQ. A rule in monitor mode produces a trigger record and no response signal at all, so a monitored rule's matches are invisible from the Console by design.

Step 4: request guardrail coverage for an application​

Because guardrails are defined and attached in the Admin Dashboard, adding or changing coverage for an application is a request to the operator team rather than a self-service action in the Console. A request that the operator can act on without a round trip includes:

  • The project and API key or keys the application uses, identified by name (for example, project checkout and key checkout-service-prod). Naming both ties the request to the policy boundary and the traffic path.
  • The content of concern: the categories of data or content that must be controlled, such as customer PII in prompts or disallowed categories in responses.
  • The required action: whether matched content should be redacted so the request still completes, or blocked so it does not. Redaction preserves functionality at the cost of altered content; blocking prioritises safety at the cost of failed requests. The right choice depends on the workload.
  • The direction: whether the concern is on the request (outbound to the model provider), the response (inbound to the application), or both.
  • The expected traffic shape: a representative example of a prompt and response helps the operator choose a check type and provider and tune the threshold without guesswork.

The operator translates this into a concrete rule on the project's guardrail and validates it in monitor mode before enforcement. The mechanics of that work are covered in the operator guides linked under What to do next. Because monitor mode produces no response signal, the first observable effect on the application side is the one that appears when the rule is promoted to enforce.

Step 5: reason about guardrails alongside routing and fallbacks​

Guardrails and routing operate on the same request but answer different questions. Routing decides which backend serves a request; a guardrail decides whether and in what form the content is allowed to pass. Because the guardrail is enforced on the gateway rather than per provider, a few properties hold regardless of routing configuration:

  • Guardrails apply across every backend. A request protected by a PII guardrail is inspected the same way whether routing sends it to the primary model or, after a failure, to a fallback. The protection does not have to be reconfigured per provider, and switching providers does not silently drop it. See Improve resilience with fallbacks for the failover behaviour itself.
  • A block is not a failure that fallback should retry. Walking a fallback chain is the gateway's response to a backend that failed to serve a request. A request blocked by a guardrail was refused on content grounds, not failed on availability grounds, so it is not a candidate for failover to another backend; another provider would refuse the same content for the same reason.
  • Redaction is consistent across a traffic split. Where traffic is distributed by weight across two backends, a redaction guardrail sanitises content identically on whichever backend a given request lands on, so the split does not produce two different levels of protection. See Reduce cost with traffic splitting.

The practical takeaway is that guardrails compose cleanly with routing: protection is a property of the project, applied uniformly across backends, rather than something that has to be re-established for each model provider a request might reach.

What to do next​

Where to go next

Monitor traffic and usage

The Request Logs workflow used to locate a refused request.

Route requests across providers

The routing setup that guardrails are layered on top of.