Passer au contenu principal
Une requête a renvoyé HTTP 400 et votre agent s’est figé. Avant de changer quoi que ce soit dans votre code, la passerelle vous a déjà dit ce qui s’est passé : le code d’erreur nomme quel contrôle s’est déclenché, et l’un de deux flux nomme la règle exacte. Cette page est le flux de consultation et de traçage — lisez le code, ouvrez le bon flux, trouvez la règle. Si vous ne devez retenir qu’une chose : un 400 provenant d’un contrôle de sécurité n’est pas un bug dans votre prompt. C’est une politique qui fait son travail. Votre tâche est de trouver quelle politique, puis de décider s’il faut corriger l’appel ou assouplir la règle.

​
1. Pourquoi ma requête llm a-t-elle été bloquée ? — commencez par le code d’erreur

Chaque block de sécurité sur la passerelle hébergée renvoie HTTP 400 avec un code lisible par machine dans le corps d’erreur de forme OpenAI. Ce code est la première bifurcation du chemin — il vous indique quel plan de contrôle déboguer et quel flux ouvrir. 
{
  "error": {
    "message": "tool \"shell.exec\" blocked by firewall: destructive shell command",
    "code": "firewall_blocked",
    "type": "invalid_request_error"
  }
}

guardrail_blocked

Une règle de contenu Guardrail s’est déclenchée sur l’entrée de votre requête ou la sortie du modèle. Tracez-la dans le flux Matches. Voir §2.

firewall_blocked

Une règle Firewall a refusé un appel d’outil. Tracez-la dans le flux Events. Voir §3.

firewall_approval_pending

Un appel d’outil est mis en attente d’approbation humaine — pas refusé. Résolvez-le, ne le déboguez pas. Voir §4.
Les trois codes sont skip-retry : ré-exécuter l’appel identique route vers la même politique et bloque à nouveau. Réessayer est de la latence gaspillée — corrigez plutôt l’entrée ou la règle. La table complète des codes vit dans Codes d’erreur.

​
2. guardrail_blocked — trouver la règle dans Matches

guardrail_blocked signifie qu’une politique de contenu attachée à votre clé (ou le défaut de votre espace de travail) a exécuté une action block contre l’entrée de la requête ou la sortie du modèle. Le message de block nomme le guardrail et la règle, et la requête ne vous coûte aucun quota — les blocks d’entrée se déclenchent avant le décompte ; les blocks de sortie remboursent le quota pré-consommé. Tracez-le :
1

Ouvrir le flux Matches

Dans la console, allez à l’onglet Matches sur la page Guardrails (GET /api/guardrail/match, Member). Chaque règle qui se déclenche atterrit ici — son RuleType, son Action, son Stage, et une chaîne Detail comme pii: email, phone ou matched 3 keyword(s).
2

Filtrer sur le block

Filtrez par action = block et l’heure de votre requête. La ligne correspondante vous indique le type de règle (pii, regex, keyword, max_chars, llm_judge, grounding, external) et si elle s’est déclenchée sur l’étape input ou output.
3

Voir ce qu'elle a réellement matché

Par défaut, le flux enregistre *qu’*une règle s’est déclenchée et sa méta-chaîne Detail — pas la sous-chaîne correspondante. Activez Log raw content sur ce guardrail (désactivé par défaut, la posture conservatrice côté vie privée) pour capturer la chaîne fautive à des fins de triage. Le réglage n’est pas rétroactif.
Un block que vous croyez erroné ? Ouvrez la correspondance et marquez-la comme faux positif (POST /api/guardrail/match/:id/mark-fp, Admin). Pour prouver le correctif avant de l’expédier, éditez la règle et ré-exécutez l’échantillon dans l’onglet Test de l’éditeur de guardrail — aucun appel amont, aucun quota.

​
Un exemple concret

Vous envoyez une réponse de support qui contient le SSN d’un client. Votre guardrail pii-shield a un override entity_actions qui bloque sur ssn : 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "ssn"],
  "entity_actions": { "ssn": "block" }
}
La passerelle renvoie 400 guardrail_blocked. Le flux Matches affiche RuleType: pii, Action: block, Stage: input, Detail: pii: ssn. Le correctif est une décision produit, pas un changement de code : assouplissez l’override en mask (le modèle ne voit jamais le SSN, l’appel passe), ou gardez le block et retirez le SSN en amont. Voir Guardrails pour la référence complète des types de règles et des entités PII.

​
3. firewall_blocked — trouver le verdict dans Events

firewall_blocked signifie qu’une politique Firewall a refusé un appel d’outil. Sur la surface inbound, il remonte comme un 400 ; à travers la passerelle MCP, il remonte comme une erreur d’outil (firewall deny: <reason>) afin que le modèle puisse réagir au lieu de planter. Le metadata de l’erreur porte le code de raison, les facteurs de risque et le score. Tracez-le dans le flux Events (GET /api/workspace/firewall/events, Developer+) — l’enregistrement brut derrière chaque évaluation. Chaque événement porte un verdict et la surface sur laquelle il a été vu :
VerdictCe qu’il signifie pour votre block
denyUne règle (ou le default_verdict) a bloqué l’appel. C’est votre firewall_blocked.
auditAutorisé mais journalisé — y compris un [shadow] « would deny » si la politique est en mode shadow.
cap_costLa dépense accumulée de l’exécution a franchi un plafond en centimes par règle ; se résout en un deny.
1

Filtrer Events sur le refus

Filtrez par verdict=deny, puis par tool, run_id, ou session_id pour isoler l’appel exact. L’événement nomme la règle correspondante et la surface — inbound, response, mcp, ou egress.
2

Lire la raison sur la règle correspondante

La chaîne de raison (par ex. destructive shell command, egress host not allowed) vous indique si la règle a matché sur le nom de l’outil, une clause args_match, ou une destination d’egress. Le glossaire des verdicts et la référence glob et JSONPath décodent la correspondance.
3

Confirmer avec le sandbox Test

Rejouez le même appel d’outil dans l’onglet Test du Firewall (POST /api/workspace/firewall/test, Developer+) pour voir le verdict, la règle correspondante et la raison — rien n’est dispatché, rien n’est journalisé.
Un deny cap_cost n’est pas un raté de règle — votre exécution d’agent a atteint le plafond de dépense que vous avez fixé. Soit l’exécution boucle (vérifiez le récapitulatif Runs et le flux d’anomalies pour un retry_loop), soit le plafond est réellement trop bas pour la tâche. Relevez le plafond délibérément, ne vous contentez pas de réessayer.

​
4. firewall_approval_pending — c’est en attente, pas refusé

firewall_approval_pending est le seul 400 que vous ne devriez pas traiter comme un block. Un verdict pending_approval a mis l’appel d’outil en attente d’un humain ; le corps d’erreur porte un id d’approbation. L’appel n’a pas échoué — il attend.
  1. Un relecteur le résout — depuis la console (Developer+) ou via votre propre callback webhook HMAC (POST /api/v1/firewall/approvals/:id/callback).
  2. Votre agent interroge GET /api/v1/firewall/approvals/:id (token de passerelle) sur l’id issu de l’erreur.
  3. Une fois approuvé, re-soumettez l’appel d’origine avec l’en-tête à usage unique X-OrcaRouter-Firewall-Approval, et la passerelle le laisse passer cette fois-là.
Voir Firewall → Approbation humaine pour la boucle HITL complète.

​
5. Pas un block de sécurité ? Écartez d’abord la clé

Tout 400 n’est pas un verdict de guardrail ou de firewall. Avant de plonger dans les flux, écartez les contraintes de clé — celles-ci rejettent avant qu’une politique ne s’exécute et ne portent pas les codes de sécurité ci-dessus :
La liste d’autorisation model_limits de la clé n’inclut pas le modèle demandé. Les requêtes pour un modèle hors de la liste sont rejetées d’emblée. Ajoutez le modèle à la clé ou appelez-en un qui est autorisé.
La clé a une liste d’autorisation allow_ips et la requête provient d’une adresse en dehors. Ajoutez l’IP / le CIDR de l’appelant ou appelez depuis un réseau autorisé.
Le plafond credit_limit_usd de la clé est épuisé (0 signifie illimité). Relevez le plafond ou basculez vers une clé avec de la marge.
Les hooks de passerelle (evaluate, dispatch MCP) requièrent une clé avec is_firewall_gateway=true. Une clé de relais ordinaire reçoit un 403. Frappez une clé scopée à la passerelle firewall pour ces routes.

​
6. Le flux de triage en deux minutes

Block sur le texte du prompt ou de la réponse

Le code est guardrail_blocked → ouvrez Matches, filtrez action=block, lisez le Stage + Detail. Corrigez le contenu ou la règle ; prouvez-le dans l’onglet Test du guardrail.

Block sur un appel d'outil

Le code est firewall_blocked → ouvrez Events, filtrez verdict=deny, lisez la surface + la raison. Corrigez l’appel ou la règle ; prouvez-le dans l’onglet Test du firewall.

L'appel est en attente

Le code est firewall_approval_pending → interrogez l’id d’approbation et re-soumettez avec l’en-tête d’approbation. Rien à déboguer.

Aucun des cas ci-dessus

Aucun code de sécurité → vérifiez la clé : model_limits, allow_ips, credit_limit_usd, ou 403 pour une portée de passerelle manquante.

​
7. Références associées

Codes d'erreur

La table complète des codes — chaque block, mise en attente et rejet que la passerelle peut renvoyer.

Glossaire des verdicts

Ce que signifie chaque verdict firewall et quand il se résout en un deny.

Glob et JSONPath

Décodez le tool_name_glob et le args_match qui ont matché votre appel.

Guardrails vs Firewall

Quel plan s’est déclenché — filtrage de texte ou gouvernance d’action.
Pour les contrôles eux-mêmes, voir Guardrails et Firewall ; pour les menaces qu’ils arrêtent, commencez au modèle de menace.