Zum Hauptinhalt springen
Wenn ein Guardrail einen Aufruf ablehnt, antwortet das Gateway Ihrer Anwendung mit HTTP 400 und dem Fehlercode guardrail_blocked. Diese Seite ist die Landing-Referenz für genau diesen einen Fehler: wie der Body aussieht, warum er sich so verhält und wie man ihn in Client-Code behandelt. Für die Policy-Engine dahinter siehe Guardrails-Überblick und die vollständige Referenz.

​
1. Wann Sie guardrail_blocked sehen

Ein Guardrail ist eine geordnete Liste von Regeln, die das Gateway gegen den Request-Input und den Modell-Output ausführt. Wenn eine Regel, deren Action block ist, feuert, wird der Aufruf abgelehnt — das Upstream-Modell wird nie aufgerufen (Input-Stage) oder seine Antwort wird zurückgehalten (Output-Stage). Der Client erhält eine 400, die guardrail_blocked trägt. Keine andere Action erzeugt diesen Fehler. mask redigiert den Treffer und lässt den bereinigten Text durch, flag zeichnet einen Match auf, ohne den Traffic zu ändern, und die prompt-formenden Actions (annotate, spotlight) lassen den Aufruf fortfahren, während sie eine Notiz hinzufügen oder nicht vertrauenswürdigen Text einfassen. Von den fünf Actions lehnt nur block ab. Siehe Actions.
guardrail_blocked ist eine Content-Ablehnung (Text rein, Text raus). Die ergänzende Tool-Policy-Verweigerung ist firewall_blocked von der Agent-Firewall — ein anderer Fehler mit einer anderen Form. Siehe Guardrails vs. Firewall.

​
2. Der Response-Body

Der Block wird im standardmäßigen OpenAI-förmigen Error-Envelope des Gateways zurückgegeben. An einem OpenAI-artigen Endpunkt (/v1/chat/completions, /v1/responses): 
{
  "error": {
    "message": "request blocked by guardrail \"pii-shield\": pii(ssn)",
    "type": "orcarouter_api_error",
    "param": "",
    "code": "guardrail_blocked"
  }
}
Die Felder, auf die Sie abstellen:
Der stabile Maschinen-Identifier. Verzweigen Sie hierauf, nicht auf den Message-String. Er ist auf jedem Endpunkt derselbe Wert und nie lokalisiert.
Menschenlesbar. Die Form ist request blocked by guardrail "<name>": <detail>, wobei <detail> die ausgelösten Regeltyp(en) als <type>(<rule-detail>) zusammenfasst — zum Beispiel pii(pii: ssn) oder keyword(matched 1 keyword(s)). Ein Block der Output-Stage liest sich response blocked by guardrail "<name>": <detail>, sodass das Verb Ihnen sagt, welche Stage den Aufruf abgelehnt hat. Die Nachricht durchläuft das Maskieren sensibler Informationen, bevor sie das Gateway verlässt, also erwarten Sie hier nicht den rohen gematchten Teilstring.
Der generische Gateway-Fehlertyp an OpenAI-artigen Endpunkten. Das unterscheidende Signal ist code, nicht type.
An der nativen Anthropic-Oberfläche (/v1/messages) ist der Envelope Claude-förmig — {"error": {"type": ..., "message": ...}} — und guardrail_blocked taucht im type-Feld auf, sodass ein natives Claude-SDK eine Policy-Verweigerung von einem generischen Gateway-Fehler unterscheiden kann.
Wollen Sie das exakte Verdikt, bevor Sie eine Regel ausliefern? Der Konsolen-Tab Test evaluiert die aktuelle Policy über Beispieltext ohne Upstream-Aufruf und ohne Kontingent — siehe Testing & Eval.

​
3. Warum guardrail_blocked kein Kontingent kostet

Ein blockierter Request ist kostenlos — er belastet Ihr Guthaben nie.
StageWann der Block feuertKontingent-Effekt
inputVor dem Upstream-Aufruf, vor der MessungNichts wird gemessen
outputNachdem das Modell geantwortet hat, bevor die Antwort zurückkehrtVorab verbrauchtes Kontingent wird zurückerstattet
Ein Input-Block wird also nicht berechnet, weil die Messung noch nicht stattgefunden hat, und ein Output-Block kehrt die Reservierung um, die das Gateway vor dem Weiterleiten platziert hat. In beiden Fällen zahlt der Aufrufer für den Block mit einer 400, nicht mit Credits. Siehe Input-Stage und Output-Stage.

​
4. Warum guardrail_blocked keinen Retry macht

Der Fehler ist als skip-retry getaggt. Das eigene Routing des Gateways wird diesen Request nicht an einen anderen Channel umschalten, weil der Block eine Eigenschaft Ihres Inhalts und Ihrer Policy ist — das erneute Ausführen des identischen Prompts würde am nächsten Channel einfach wieder blockieren und den Versuch verschwenden.
Setzen Sie guardrail_blocked auch nicht in die Retry-Schleife Ihres Clients. Er ist deterministisch: derselbe Prompt gegen dieselbe Policy blockiert jedes Mal. Ein Retry verbrennt Latenz für ein Ergebnis, das sich nicht ändern kann. Behandeln Sie ihn als terminale Ablehnung — korrigieren Sie den Input oder korrigieren Sie die Policy.

​
5. Behandlung in Client-Code

Verzweigen Sie auf das code-Feld und bringen Sie dem Endnutzer eine nützliche Nachricht zur Oberfläche, statt einen Retry zu machen. 
import httpx

resp = httpx.post(
    "https://api.orcarouter.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-orca-..."},
    json={
        "model": "openai/gpt-4o-mini",
        "messages": [{"role": "user", "content": "My SSN is 123-45-6789"}],
    },
)

if resp.status_code == 400:
    err = resp.json().get("error", {})
    if err.get("code") == "guardrail_blocked":
        # Terminal — do not retry. Tell the user what to change.
        raise ValueError(f"Blocked by policy: {err['message']}")

resp.raise_for_status()
Der sk-orca-...-Key hier ist ein Relay-Key — er trägt nur /v1/*-Traffic. Sie bearbeiten ein Guardrail nie damit; das Verfassen und Anhängen von Policy ist eine Konsolen-/Management-API-Aktion auf Ihrer Session, und das Erstellen oder Bearbeiten eines Guardrails erfordert die Rolle Developer+.

​
6. Einen Block bestätigen und tunen

Jede Regel, die feuert — Block eingeschlossen — landet im Workspace-Matches-Feed mit ihrem Type, Action, Stage und einem Detail-String. Dort bestätigen Sie, welche Regel einen gegebenen Aufruf abgelehnt hat, und triagieren Fehlalarme.

Matches-Feed

Sehen Sie jeden Block, Mask und Flag mit Type, Action und Stage. Der gematchte Teilstring erscheint nur, wenn Log raw content an ist.

Logging & Datenschutz

Rohinhalt ist standardmäßig aus — die datenschutzfreundliche Haltung. Schalten Sie ihn pro Guardrail ein, wenn Sie den Teilstring zum Triage brauchen.

Fehlalarme tunen

Ein Fehlalarm ist ein Tuning-Signal, kein Grund, die Regel zu deaktivieren. Markieren Sie ihn und verengen Sie das Muster.

Versionierung

Policy geändert und wollen es rückgängig machen? Diffen Sie beliebige zwei Versionen und reverten Sie als neue Version — die Historie wird nie mutiert.
Bei einer streamenden Response gilt ein Output-block weiterhin: der Scanner kappt den Stream mittendrin, bevor blockierter Inhalt den Client erreicht. Output-mask gilt auf Streams ebenfalls in-band — der Scanner schreibt den Treffer im rollenden Puffer um, bevor das sichere Präfix ausgegeben wird. Siehe Streaming-Abdeckung und stream-sichere Regeln.

​
7. Verwandt