Codes d'erreur de sécurité

Lorsqu’un guardrail ou le firewall arrête une requête, OrcaRouter renvoie une erreur typée sur laquelle votre code peut brancher — pas un vague 400. Trois codes de sécurité couvrent les cas que vous rencontrerez : un prompt ou une réponse filtré, un appel d’outil refusé, et un appel d’outil mis en attente d’approbation humaine. Cette page est la référence de ces codes — le cas d’usage de chacun, le statut HTTP exact, ce qu’il vous coûte, et la seule règle qui compte le plus : votre logique de retry doit les traiter comme des cas particuliers. Les trois sont marqués skip-retry ; ré-exécuter aveuglément le même appel ne fait que redéclencher le même contrôle.

Ce sont des codes d’application — la passerelle décidant de ne pas transmettre votre appel. Ils sont distincts des erreurs du fournisseur amont (un modèle 429, un dépassement de contexte) et des échecs d’authentification. Pour savoir pourquoi une requête spécifique a été arrêtée, voir Pourquoi a-ce été bloqué ?.

1. Les codes d’erreur de sécurité llm en un coup d’œil

Chaque block de sécurité renvoie un HTTP 400 avec un corps d’erreur de forme OpenAI (error.code est la chaîne typée ci-dessous). Sur les routes Claude natives (/v1/messages), le même code voyage dans la forme d’erreur Claude, de sorte que le routage du SDK est déterministe à travers les protocoles.

Code	Arrête	Coût en quota
`guardrail_blocked`	Un prompt ou une réponse qui a heurté une règle `block`	Aucun
`firewall_blocked`	Un appel d’outil / annonce refusé	Aucun token de modèle
`firewall_approval_pending`	Un appel d’outil mis en attente d’un relecteur humain	Aucun token de modèle

Branchez sur error.code, jamais sur la chaîne du message. Les messages nomment le guardrail, la règle ou l’outil spécifique et changeront ; les codes sont un contrat stable.

2. `guardrail_blocked` — un prompt ou une réponse filtré

Renvoyé lorsqu’une règle de guardrail avec l’action block se déclenche — un mot-clé sur liste de refus, une correspondance regex, une entité PII ou secret que vous avez choisi de bloquer plutôt que de masquer, un verdict llm_judge, ou une vérification de grounding échouée. HTTP 400. Le message nomme le guardrail et la règle qui s’est déclenchée.

Impact sur le quota : aucun

Une requête bloquée ne coûte aucun quota. Un block à l’étape d’entrée se déclenche avant le décompte, donc rien n’est jamais facturé. Un block à l’étape de sortie s’exécute après la réponse du modèle, de sorte que la passerelle rembourse le quota pré-consommé avant de renvoyer l’erreur. Dans les deux cas, vous ne payez rien pour un appel bloqué.

Pourquoi c'est skip-retry

Le verdict est une propriété du contenu, pas du canal. Ré-exécuter le même prompt — même contre un modèle différent — produit le même block. Corrigez l’entrée (ou la politique) au lieu de réessayer.

À quoi ressemble un mask à la place

Les règles mask ne renvoient pas ce code. Une correspondance masquée (par ex. jane@acme.com → [EMAIL]) est redactée sur place et l’appel se poursuit normalement — vous obtenez un 200, simplement avec le segment sensible retiré. Seule l’action block fait remonter guardrail_blocked. (flag ne change absolument rien au trafic.)

{
  "error": {
    "type": "openai_error",
    "code": "guardrail_blocked",
    "message": "request blocked by guardrail \"pii-shield\": rule ssn (block)"
  }
}

Pour les types de règles, les étapes et les actions derrière ce code, voir Guardrails. Pour l’enveloppe d’erreur champ par champ, voir Payloads de webhook et d’erreur.

3. `firewall_blocked` — un appel d’outil refusé

Renvoyé lorsque le firewall résout un verdict deny pour un appel d’outil — une commande shell destructrice, un fetch en forme de SSRF, une destination d’egress sur une liste de refus, ou un skill en mode block. La manière dont le deny remonte dépend de la surface d’application :

inbound / response / egress

HTTP 400 avec error.code = firewall_blocked. Le corps porte des error.metadata structurées (reason_code, factors de risque, risk_score) afin que vous puissiez expliquer le block, pas seulement le constater.

surface mcp

Renvoyé comme une erreur d’outil (firewall deny: <reason>), pas une défaillance de transport — de sorte que le modèle voit le rejet et peut choisir un autre outil, demander à l’utilisateur, ou s’arrêter, au lieu de planter l’exécution.

sanitize n’est pas un block. Un verdict sanitize redacte les sous-chaînes correspondantes des arguments de l’appel d’outil et transmet l’appel nettoyé — il ne renvoie jamais firewall_blocked. (La seule exception : sur la surface inbound, où il n’y a pas encore d’arguments au moment de l’appel, sanitize escalade en un 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"]
    }
  }
}

Côté quota, un block inbound se déclenche avant l’appel au modèle amont, donc il ne coûte aucun token de modèle. Voir Glossaire des verdicts pour chaque verdict, et Appels d’outils dangereux pour les menaces que ce code défend.

4. `firewall_approval_pending` — mis en attente d’un humain

Renvoyé à l’instant où un appel d’outil heurte un verdict pending_approval. Un point de contrôle human-in-the-loop ne peut pas être une attente inline bloquante, donc la passerelle renvoie immédiatement une réponse held plutôt que de faire du long-polling. HTTP 400. L’erreur porte l’id d’approbation afin que votre agent sache quelle mise en attente résoudre. C’est le seul code auquel vous répondez en résolvant et re-soumettant — pas en le traitant comme un échec terminal :

Lire l'id d'approbation depuis l'erreur held

L’id est récupérable depuis le corps d’erreur. Ne réessayez pas encore l’appel — un retry naïf ne fait que remettre en attente.

Attendre une décision

Un relecteur le résout depuis la console (Developer+), ou votre système d’approbation reçoit un callback webhook signé HMAC. Votre agent interroge GET /api/v1/firewall/approvals/:id pour l’état.

Re-soumettre avec le token d'approbation

Une fois approuvé, ré-émettez l’appel d’origine en portant l’en-tête à usage unique X-OrcaRouter-Firewall-Approval. La passerelle reconnaît l’id et laisse passer cet appel-là.

Les routes d’approbation (/api/v1/firewall/approvals/*) s’exécutent sur une clé scopée à la passerelle firewall, pas sur votre session de console. Voir Approbation humaine (HITL) pour la boucle complète et Payloads de webhook pour la signature du callback.

5. Pourquoi les trois ignorent le retry

La logique de retry standard d’un SDK suppose qu’un 400 pourrait réussir au second essai. Ces codes brisent cette hypothèse — le block est déterministe, donc un retry aveugle gaspille un aller-retour et (pour les appels en attente) re-met silencieusement en file une approbation.

Ce que « skip-retry » signifie en pratique

La machinerie interne de retry/fallback d’OrcaRouter ne ré-essaie jamais contre un autre canal un appel qui renvoie l’un de ces codes. Reproduisez cela dans votre client : sur un code de sécurité, arrêtez-vous et agissez sur le verdict, ne bouclez pas.

La bonne réaction par code

guardrail_blocked → corrigez l’entrée ou assouplissez la politique ; faites remonter le refus à l’utilisateur. Ne réessayez pas.
firewall_blocked → l’action est interdite ; faites en sorte que l’agent choisisse un autre outil ou demande de l’aide. Ne réessayez pas.
firewall_approval_pending → résolvez la mise en attente, puis re-soumettez une fois avec l’en-tête d’approbation (§4). Un retry sans l’en-tête remet en attente.

6. Récapitulatif quota et facturation

Un block de sécurité ne vous facture jamais l’unité de travail bloquée.

Code	Quand il se déclenche	Issue de facturation
`guardrail_blocked` (entrée)	Avant l’appel au modèle	Jamais décompté
`guardrail_blocked` (sortie)	Après la réponse du modèle	Quota pré-consommé remboursé
`firewall_blocked` (inbound)	Avant l’appel au modèle	Aucun token de modèle
`firewall_approval_pending`	Avant le dispatch	Aucun token de modèle

Une règle llm_judge ou grounding de guardrail appelle bien un modèle pour atteindre son verdict, et ces tokens de juge sont facturés comme une sous-ligne de juge distincte — même lorsque le verdict est un block. C’est le coût de la vérification, pas celui de la requête bloquée elle-même.

7. Références associées

Pourquoi a-ce été bloqué ?

Tracez un seul block jusqu’à la règle, la surface et la raison exactes qui l’ont produit.

Glossaire des verdicts

Chaque verdict firewall — allow, audit, deny, sanitize, pending_approval, cap_cost — et ce que chacun émet.

Payloads de webhook et d'erreur

L’enveloppe d’erreur complète, les champs error.metadata, et la signature du callback d’approbation.

Modes d'application

Shadow, observe et enforce — quand un verdict change réellement le trafic.

Pour les contrôles qui produisent ces codes, voir Guardrails et Firewall ; pour le vocabulaire, voir le Glossaire des concepts.

​1. Les codes d’erreur de sécurité llm en un coup d’œil

​2. guardrail_blocked — un prompt ou une réponse filtré

​3. firewall_blocked — un appel d’outil refusé

inbound / response / egress

surface mcp

​4. firewall_approval_pending — mis en attente d’un humain

​5. Pourquoi les trois ignorent le retry

​6. Récapitulatif quota et facturation

​7. Références associées

Pourquoi a-ce été bloqué ?

Glossaire des verdicts

Payloads de webhook et d'erreur

Modes d'application

1. Les codes d’erreur de sécurité llm en un coup d’œil

2. `guardrail_blocked` — un prompt ou une réponse filtré

3. `firewall_blocked` — un appel d’outil refusé

4. `firewall_approval_pending` — mis en attente d’un humain

5. Pourquoi les trois ignorent le retry

6. Récapitulatif quota et facturation

7. Références associées