Zum Hauptinhalt springen
Ein Request gab HTTP 400 zurück und Ihr Agent ist ins Stocken geraten. Bevor Sie irgendeinen Code ändern, hat das Gateway Ihnen bereits gesagt, was passiert ist: Der Fehlercode benennt, welche Kontrolle gefeuert hat, und einer von zwei Feeds benennt die exakte Regel. Diese Seite ist der Nachschlag-und-Verfolge-Flow — lesen Sie den Code, öffnen Sie den richtigen Feed, finden Sie die Regel. Wenn Sie sich nur eine Sache merken: Ein 400 von einer Sicherheitskontrolle ist kein Bug in Ihrem Prompt. Es ist eine Policy, die ihre Arbeit tut. Ihre Aufgabe ist es, herauszufinden, welche Policy, und dann zu entscheiden, ob Sie den Aufruf beheben oder die Regel lockern.

​
1. Warum wurde mein LLM-Request blockiert? — beginnen Sie mit dem Fehlercode

Jeder Sicherheitsblock auf dem gehosteten Gateway gibt HTTP 400 mit einem maschinenlesbaren code im OpenAI-förmigen Fehler-Body zurück. Dieser Code ist die erste Weggabelung — er sagt Ihnen, welche Control-Plane Sie debuggen und welchen Feed Sie öffnen müssen. 
{
  "error": {
    "message": "tool \"shell.exec\" blocked by firewall: destructive shell command",
    "code": "firewall_blocked",
    "type": "invalid_request_error"
  }
}

guardrail_blocked

Eine Guardrail-Inhaltsregel hat auf Ihren Request-Input oder die Modellausgabe gefeuert. Verfolgen Sie es im Matches-Feed. Siehe §2.

firewall_blocked

Eine Firewall-Regel hat einen Tool-Call abgelehnt. Verfolgen Sie es im Events-Feed. Siehe §3.

firewall_approval_pending

Ein Tool-Call ist für eine menschliche Freigabe zurückgehalten — nicht abgelehnt. Lösen Sie es auf, debuggen Sie es nicht. Siehe §4.
Alle drei Codes sind skip-retry: Denselben Aufruf identisch erneut auszuführen routet zu derselben Policy und blockiert wieder. Ein Retry ist verschwendete Latenz — beheben Sie stattdessen den Input oder die Regel. Die vollständige Code-Tabelle steht in Fehlercodes.

​
2. guardrail_blocked — die Regel in Matches finden

guardrail_blocked bedeutet, dass eine an Ihren Key (oder Ihren Workspace-Default) angehängte Inhaltspolicy eine block-Aktion gegen den Request-Input oder die Modellausgabe ausgeführt hat. Die Block-Nachricht benennt das Guardrail und die Regel, und der Request kostet Sie kein Kontingent — Input-Blocks feuern vor der Messung; Output-Blocks erstatten das vorab verbrauchte Kontingent. So verfolgen Sie es:
1

Öffnen Sie den Matches-Feed

Gehen Sie in der Konsole zum Matches-Tab auf der Guardrails-Seite (GET /api/guardrail/match, Member). Jede Regel, die feuert, landet hier — ihr RuleType, ihre Action, ihre Stage und ein Detail-String wie pii: email, phone oder matched 3 keyword(s).
2

Filtern Sie auf den Block

Filtern Sie nach action = block und der Zeit Ihres Requests. Die gematchte Zeile sagt Ihnen den Regeltyp (pii, regex, keyword, max_chars, llm_judge, grounding, external) und ob sie im input- oder output-Stage gefeuert hat.
3

Sehen Sie, was sie tatsächlich gematcht hat

Standardmäßig zeichnet der Feed auf, dass eine Regel gefeuert hat, und ihren Detail-Meta-String — nicht den gematchten Teilstring. Schalten Sie Log raw content auf diesem Guardrail ein (es ist standardmäßig aus, die datenschutzkonservative Haltung), um den anstößigen String zur Triage zu erfassen. Der Schalter ist nicht rückwirkend.
Ein Block, den Sie für falsch halten? Öffnen Sie den Match und markieren Sie ihn als False Positive (POST /api/guardrail/match/:id/mark-fp, Admin). Um den Fix zu beweisen, bevor Sie ihn ausliefern, bearbeiten Sie die Regel und führen Sie das Sample im Test-Tab des Guardrail-Editors erneut aus — kein Upstream-Aufruf, kein Kontingent.

​
Ein konkretes Beispiel

Sie senden eine Support-Antwort, die eine Kunden-SSN enthält. Ihr pii-shield- Guardrail hat ein entity_actions-Override, das auf ssn blockiert: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "ssn"],
  "entity_actions": { "ssn": "block" }
}
Das Gateway gibt 400 guardrail_blocked zurück. Der Matches-Feed zeigt RuleType: pii, Action: block, Stage: input, Detail: pii: ssn. Der Fix ist eine Produktentscheidung, keine Code-Änderung: Lockern Sie das Override auf mask (das Modell sieht die SSN nie, der Aufruf geht durch), oder behalten Sie den Block bei und entfernen Sie die SSN upstream. Siehe Guardrails für die vollständige Regeltyp- und PII-Entitäten-Referenz.

​
3. firewall_blocked — das Verdikt in Events finden

firewall_blocked bedeutet, dass eine Firewall-Policy einen Tool-Call abgelehnt hat. Auf der inbound-Surface zeigt es sich als 400; durch das MCP-Gateway zeigt es sich als Tool-Fehler (firewall deny: <reason>), sodass das Modell reagieren kann, statt abzustürzen. Die Fehler-metadata trägt den Reason-Code, die Risikofaktoren und den Score. Verfolgen Sie es im Events-Feed (GET /api/workspace/firewall/events, Developer+) — dem Rohdatensatz hinter jeder Auswertung. Jedes Event trägt ein Verdikt und die Surface, auf der es gesehen wurde:
VerdiktWas es für Ihren Block bedeutet
denyEine Regel (oder das default_verdict) hat den Aufruf blockiert. Das ist Ihr firewall_blocked.
auditErlaubt, aber geloggt — einschließlich eines [shadow] „would deny”, wenn die Policy im Shadow-Mode ist.
cap_costDie kumulierten Ausgaben des Runs haben eine Pro-Regel-Cent-Obergrenze überschritten; löst sich zu einem Deny auf.
1

Filtern Sie Events auf die Ablehnung

Filtern Sie nach verdict=deny, dann nach tool, run_id oder session_id, um den exakten Aufruf zu isolieren. Das Event benennt die gematchte Regel und die Surface — inbound, response, mcp oder egress.
2

Lesen Sie den Grund auf der gematchten Regel

Der Grund-String (z. B. destructive shell command, egress host not allowed) sagt Ihnen, ob die Regel auf dem Tool-Namen, einer args_match-Klausel oder einem Egress-Ziel gematcht hat. Das Verdikt-Glossar und die Glob- & JSONPath-Referenz dekodieren das Matching.
3

Bestätigen Sie mit der Test-Sandbox

Spielen Sie denselben Tool-Call im Firewall-Test-Tab erneut ab (POST /api/workspace/firewall/test, Developer+), um das Verdikt, die gematchte Regel und den Grund zu sehen — nichts dispatcht, nichts geloggt.
Ein cap_cost-Deny ist kein Regel-Fehlauslöser — Ihr Agentenlauf hat die Ausgabenobergrenze erreicht, die Sie gesetzt haben. Entweder schleift der Run (prüfen Sie den Runs-Rollup und den Anomalie-Feed auf einen retry_loop) oder die Obergrenze ist für die Aufgabe ehrlich zu niedrig. Heben Sie die Obergrenze bewusst an, versuchen Sie es nicht einfach erneut.

​
4. firewall_approval_pending — es ist zurückgehalten, nicht abgelehnt

firewall_approval_pending ist der eine 400, den Sie nicht als Block behandeln sollten. Ein pending_approval-Verdikt hat den Tool-Call für einen Menschen zurückgehalten; der Fehler-Body trägt eine Approval-ID. Der Aufruf ist nicht fehlgeschlagen — er wartet.
  1. Ein Prüfer löst es auf — über die Konsole (Developer+) oder über Ihren eigenen HMAC-Webhook-Callback (POST /api/v1/firewall/approvals/:id/callback).
  2. Ihr Agent pollt GET /api/v1/firewall/approvals/:id (Gateway-Token) auf die ID aus dem Fehler.
  3. Sobald genehmigt, reichen Sie den ursprünglichen Aufruf mit dem einmal nutzbaren X-OrcaRouter-Firewall-Approval-Header erneut ein, und das Gateway lässt ihn dieses eine Mal durch.
Siehe Firewall → Menschliche Freigabe für die vollständige HITL-Schleife.

​
5. Kein Sicherheitsblock? Schließen Sie zuerst den Key aus

Nicht jeder 400 ist ein Guardrail- oder Firewall-Verdikt. Bevor Sie ins Feed-Tauchen gehen, schließen Sie die Key-Constraints aus — diese lehnen ab, bevor irgendeine Policy läuft, und tragen nicht die obigen Sicherheitscodes:
Die model_limits-Allowlist des Keys schließt das angefragte Modell nicht ein. Requests für ein Modell außerhalb der Liste werden vorab abgelehnt. Fügen Sie das Modell dem Key hinzu oder rufen Sie eines auf, das erlaubt ist.
Der Key hat eine allow_ips-Allowlist und der Request kam von einer Adresse außerhalb davon. Fügen Sie die IP / CIDR des Aufrufers hinzu oder rufen Sie aus einem erlaubten Netzwerk auf.
Die credit_limit_usd-Obergrenze des Keys ist erschöpft (0 bedeutet unbegrenzt). Heben Sie die Obergrenze an oder wechseln Sie zu einem Key mit Spielraum.
Die Gateway-Hooks (evaluate, MCP-Dispatch) erfordern einen Key mit is_firewall_gateway=true. Ein regulärer Relay-Key erhält 403. Prägen Sie einen firewall-gateway-scoped Key für diese Routen.

​
6. Der Zwei-Minuten-Triage-Flow

Block auf Prompt- oder Antworttext

Code ist guardrail_blocked → öffnen Sie Matches, filtern Sie action=block, lesen Sie Stage + Detail. Beheben Sie den Inhalt oder die Regel; beweisen Sie es im Guardrail-Test-Tab.

Block auf einem Tool-Call

Code ist firewall_blocked → öffnen Sie Events, filtern Sie verdict=deny, lesen Sie Surface + Grund. Beheben Sie den Aufruf oder die Regel; beweisen Sie es im Firewall-Test-Tab.

Aufruf ist zurückgehalten

Code ist firewall_approval_pending → pollen Sie die Approval-ID und reichen Sie mit dem Approval-Header erneut ein. Nichts zu debuggen.

Nichts davon

Kein Sicherheitscode → prüfen Sie den Key: model_limits, allow_ips, credit_limit_usd oder 403 für einen fehlenden Gateway-Scope.

​
7. Verwandte Referenzen

Fehlercodes

Die vollständige Code-Tabelle — jeder Block, Hold und jede Ablehnung, die das Gateway zurückgeben kann.

Verdikt-Glossar

Was jedes Firewall-Verdikt bedeutet und wann es sich zu einem Deny auflöst.

Glob & JSONPath

Dekodieren Sie das tool_name_glob und args_match, das Ihren Aufruf gematcht hat.

Guardrails vs. Firewall

Welche Plane gefeuert hat — Text-Screening oder Aktions-Governance.
Für die Kontrollen selbst siehe Guardrails und Firewall; für die Bedrohungen, die sie stoppen, beginnen Sie beim Bedrohungsmodell.