Zum Hauptinhalt springen
Wenn ein Guardrail oder die Firewall einen Request stoppt, gibt OrcaRouter einen typisierten Fehler zurück, auf den Ihr Code verzweigen kann — keinen vagen 400. Drei Sicherheitscodes decken die Fälle ab, die Ihnen begegnen: ein gescreenter Prompt oder eine gescreente Antwort, ein abgelehnter Tool-Call und ein Tool-Call, der für eine menschliche Freigabe zurückgehalten wird. Diese Seite ist die Referenz für diese Codes — der Anwendungsfall für jeden, der exakte HTTP-Status, was er Sie kostet, und die eine Regel, die am wichtigsten ist: Retry-Logik muss sie als Sonderfall behandeln. Alle drei sind als skip-retry markiert; denselben Aufruf blind erneut auszuführen löst einfach wieder dieselbe Kontrolle aus.
Dies sind Durchsetzungs-Codes — das Gateway entscheidet, Ihren Aufruf nicht weiterzuleiten. Sie sind verschieden von Upstream-Anbieterfehlern (ein Modell-429, ein Context-Overflow) und von Auth-Fehlern. Warum ein bestimmter Request gestoppt wurde, beschreibt Warum wurde das blockiert?.

​
1. Die LLM-Sicherheits-Fehlercodes auf einen Blick

Jeder Sicherheitsblock gibt HTTP 400 mit einem OpenAI-förmigen Fehler-Body zurück (error.code ist der typisierte String unten). Auf nativen Claude-Routen (/v1/messages) reist derselbe Code in der Claude-Fehlerform, sodass das SDK-Routing protokollübergreifend deterministisch ist.
CodeStopptKontingentkosten
guardrail_blockedEinen Prompt oder eine Antwort, der/die auf eine block-Regel trafKeine
firewall_blockedEinen abgelehnten Tool-Call / ein abgelehntes AngebotKeine Modell-Tokens
firewall_approval_pendingEinen Tool-Call, der für einen menschlichen Prüfer zurückgehalten wirdKeine Modell-Tokens
Verzweigen Sie auf error.code, niemals auf den Nachrichten-String. Nachrichten benennen das spezifische Guardrail, die Regel oder das Tool und werden sich ändern; die Codes sind ein stabiler Vertrag.

​
2. guardrail_blocked — ein gescreenter Prompt oder eine Antwort

Wird zurückgegeben, wenn eine Guardrail-Regel mit der block-Aktion feuert — ein gesperrtes Keyword, ein Regex-Treffer, eine PII- oder Secret-Entität, die Sie zu blockieren statt zu maskieren gewählt haben, ein llm_judge-Verdikt oder eine fehlgeschlagene Grounding-Prüfung. HTTP 400. Die Nachricht benennt das Guardrail und die Regel, die gefeuert hat.
Ein blockierter Request kostet kein Kontingent. Ein Block im Input-Stage feuert vor der Messung, sodass nie etwas berechnet wird. Ein Block im Output-Stage läuft nachdem das Modell geantwortet hat, sodass das Gateway das vorab verbrauchte Kontingent erstattet, bevor es den Fehler zurückgibt. So oder so zahlen Sie nichts für einen blockierten Aufruf.
Das Verdikt ist eine Eigenschaft des Inhalts, nicht des Channels. Denselben Prompt erneut auszuführen — selbst gegen ein anderes Modell — erzeugt denselben Block. Beheben Sie den Input (oder die Policy), statt es erneut zu versuchen.
mask-Regeln geben diesen Code nicht zurück. Ein maskierter Treffer (z. B. jane@acme.com → [EMAIL]) wird an Ort und Stelle redigiert und der Aufruf läuft normal weiter — Sie erhalten einen 200, nur mit entferntem sensiblem Bereich. Nur die block-Aktion bringt guardrail_blocked zum Vorschein. (flag ändert am Traffic überhaupt nichts.)
{
  "error": {
    "type": "openai_error",
    "code": "guardrail_blocked",
    "message": "request blocked by guardrail \"pii-shield\": rule ssn (block)"
  }
}
Für die Regeltypen, Stages und Aktionen hinter diesem Code siehe Guardrails. Für das Feld-für-Feld-Fehler-Envelope siehe Webhook- & Fehler-Payloads.

​
3. firewall_blocked — ein abgelehnter Tool-Call

Wird zurückgegeben, wenn die Firewall ein deny-Verdikt für einen Tool-Call auflöst — ein destruktiver Shell-Befehl, ein SSRF-förmiger Fetch, ein Egress-Ziel auf einer Deny-Liste oder ein Skill im block-Mode. Wie sich das Deny zeigt, hängt von der Enforcement-Surface ab:

inbound / response / egress

HTTP 400 mit error.code = firewall_blocked. Der Body trägt strukturierte error.metadata (reason_code, Risiko-factors, risk_score), sodass Sie den Block erklären können, nicht nur sehen.

mcp-Surface

Wird als Tool-Fehler (firewall deny: <reason>) zurückgegeben, nicht als Transportfehler — sodass das Modell die Ablehnung sieht und ein anderes Tool wählen, den Nutzer fragen oder anhalten kann, statt den Run abstürzen zu lassen.
sanitize ist kein Block. Ein sanitize-Verdikt redigiert gematchte Teilstrings aus den Tool-Call-Argumenten und leitet den bereinigten Aufruf weiter — es gibt nie firewall_blocked zurück. (Die eine Ausnahme: Auf der inbound-Surface, wo es noch keine Aufruf-Argumente gibt, eskaliert sanitize zu einem Deny.)
{
  "error": {
    "type": "openai_error",
    "code": "firewall_blocked",
    "message": "tool \"shell.exec\" blocked by firewall: denied tool",
    "metadata": {
      "reason_code": "FW-TOOL-001",
      "risk_score": 92,
      "factors": ["denied_tool"]
    }
  }
}
Kontingentmäßig feuert ein inbound-Block vor dem Upstream-Modellaufruf, sodass er keine Modell-Tokens kostet. Siehe Verdikt-Glossar für jedes Verdikt und Gefährliche Tool-Calls für die Bedrohungen, gegen die dieser Code verteidigt.

​
4. firewall_approval_pending — für einen Menschen zurückgehalten

Wird in dem Moment zurückgegeben, in dem ein Tool-Call auf ein pending_approval-Verdikt trifft. Ein Human-in-the-Loop-Gate kann kein blockierendes Inline-Warten sein, sodass das Gateway sofort eine held-Antwort zurückgibt, statt per Long-Polling zu warten. HTTP 400. Der Fehler trägt die Approval-ID, sodass Ihr Agent weiß, welchen Hold er auflösen muss. Dies ist der eine Code, auf den Sie durch Auflösen und erneutes Einreichen reagieren — nicht, indem Sie ihn als terminalen Fehler behandeln:
1

Lesen Sie die Approval-ID aus dem held-Fehler

Die ID ist aus dem Fehler-Body wiederherstellbar. Versuchen Sie den Aufruf noch nicht erneut — ein naiver Retry hält ihn einfach erneut zurück.
2

Warten Sie auf eine Entscheidung

Ein Prüfer löst es über die Konsole (Developer+) auf, oder Ihr Approval-System erhält einen HMAC-signierten Webhook-Callback. Ihr Agent pollt GET /api/v1/firewall/approvals/:id auf den Zustand.
3

Reichen Sie mit dem Approval-Token erneut ein

Sobald genehmigt, geben Sie den ursprünglichen Aufruf mit dem einmal nutzbaren X-OrcaRouter-Firewall-Approval-Header erneut aus. Das Gateway erkennt die ID und lässt diesen einen Aufruf durch.
Die Approval-Routen (/api/v1/firewall/approvals/*) laufen auf einem firewall-gateway-scoped Key, nicht auf Ihrer Konsolen-Session. Siehe Menschliche Freigabe (HITL) für die vollständige Schleife und Webhook-Payloads für die Callback-Signatur.

​
5. Warum alle drei den Retry überspringen

Standard-SDK-Retry-Logik nimmt an, dass ein 400 bei einem zweiten Versuch gelingen könnte. Diese Codes brechen diese Annahme — der Block ist deterministisch, sodass ein blinder Retry einen Round-Trip verschwendet und (bei zurückgehaltenen Aufrufen) stillschweigend eine Freigabe erneut einreiht.
OrcaRouters eigene interne Retry-/Fallback-Mechanik versucht nie einen Aufruf erneut, der einen dieser Codes zurückgibt, gegen einen anderen Channel. Spiegeln Sie das in Ihrem Client: Bei einem Sicherheitscode stoppen Sie und handeln Sie nach dem Verdikt, schleifen Sie nicht.
  • guardrail_blocked → beheben Sie den Input oder lockern Sie die Policy; bringen Sie die Ablehnung dem Nutzer zur Kenntnis. Nicht erneut versuchen.
  • firewall_blocked → die Aktion ist unzulässig; lassen Sie den Agenten ein anderes Tool wählen oder um Hilfe bitten. Nicht erneut versuchen.
  • firewall_approval_pending → lösen Sie den Hold auf und reichen Sie dann einmal mit dem Approval-Header erneut ein (§4). Ein Retry ohne den Header hält erneut zurück.

​
6. Kontingent- & Abrechnungszusammenfassung

Ein Sicherheitsblock berechnet Ihnen nie die blockierte Arbeitseinheit.
CodeWann er feuertAbrechnungsergebnis
guardrail_blocked (input)Vor dem ModellaufrufNie gemessen
guardrail_blocked (output)Nachdem das Modell antwortetVorab verbrauchtes Kontingent erstattet
firewall_blocked (inbound)Vor dem ModellaufrufKeine Modell-Tokens
firewall_approval_pendingVor dem DispatchKeine Modell-Tokens
Die llm_judge- oder grounding-Regel eines Guardrails ruft doch ein Modell auf, um zu ihrem Verdikt zu gelangen, und diese Judge-Tokens werden als separate Judge-Unterzeile berechnet — selbst wenn das Verdikt ein Block ist. Das sind die Kosten der Prüfung, nicht des blockierten Requests selbst.

​
7. Verwandte Referenzen

Warum wurde das blockiert?

Verfolgen Sie einen einzelnen Block zu der exakten Regel, Surface und dem Grund, der ihn erzeugt hat.

Verdikt-Glossar

Jedes Firewall-Verdikt — allow, audit, deny, sanitize, pending_approval, cap_cost — und was jedes erzeugt.

Webhook- & Fehler-Payloads

Das vollständige Fehler-Envelope, die error.metadata-Felder und die Approval-Callback-Signatur.

Enforcement-Modes

Shadow, observe und enforce — wann ein Verdikt tatsächlich den Traffic ändert.
Für die Kontrollen, die diese Codes erzeugen, siehe Guardrails und Firewall; für das Vokabular siehe das Konzept-Glossar.