Passer au contenu principal
Quand un guardrail rejette un appel, la passerelle répond à votre application avec une HTTP 400 et le code d’erreur guardrail_blocked. Cette page est la référence d’atterrissage pour cette seule erreur : à quoi ressemble le corps, pourquoi elle se comporte comme elle le fait, et comment la gérer dans le code client. Pour le moteur de politique derrière elle, voir Vue d’ensemble des guardrails et la référence complète.

​
1. Quand vous voyez guardrail_blocked

Un guardrail est une liste ordonnée de règles que la passerelle exécute contre l’entrée de la requête et la sortie du modèle. Quand une règle dont l’action est block se déclenche, l’appel est rejeté — le modèle en amont n’est jamais appelé (étape input) ou sa réponse est retenue (étape output). Le client reçoit une 400 portant guardrail_blocked. Aucune autre action ne produit cette erreur. mask redacte la correspondance et laisse passer le texte assaini, flag enregistre une correspondance sans changer le trafic, et les actions de modelage du prompt (annotate, spotlight) laissent l’appel continuer en ajoutant une note ou en encadrant le texte non fiable. Des cinq actions, seule block rejette. Voir Actions.
guardrail_blocked est un rejet de contenu (texte en entrée, texte en sortie). Le refus de politique d’outils compagnon est firewall_blocked de l’Agent Firewall — une erreur différente avec une forme différente. Voir guardrails vs. firewall.

​
2. Le corps de réponse

Le block est renvoyé dans l’enveloppe d’erreur standard de forme OpenAI de la passerelle. Sur un endpoint de style OpenAI (/v1/chat/completions, /v1/responses) : 
{
  "error": {
    "message": "request blocked by guardrail \"pii-shield\": pii(ssn)",
    "type": "orcarouter_api_error",
    "param": "",
    "code": "guardrail_blocked"
  }
}
Les champs sur lesquels vous vous basez :
L’identifiant machine stable. Branchez sur celui-ci, pas sur la chaîne du message. C’est la même valeur sur chaque endpoint et jamais localisée.
Lisible par un humain. La forme est request blocked by guardrail "<name>": <detail>, où <detail> résume le ou les types de règles qui se sont déclenchés comme <type>(<rule-detail>) — par exemple pii(pii: ssn) ou keyword(matched 1 keyword(s)). Un block à l’étape output se lit response blocked by guardrail "<name>": <detail>, donc le verbe vous dit quelle étape a rejeté l’appel. Le message passe par le masquage des informations sensibles avant de quitter la passerelle, donc ne vous attendez pas à la sous-chaîne brute correspondante ici.
Le type d’erreur générique de la passerelle sur les endpoints de style OpenAI. Le signal distinctif est code, pas type.
Sur la surface native Anthropic (/v1/messages), l’enveloppe est de forme Claude — {"error": {"type": ..., "message": ...}} — et guardrail_blocked apparaît dans le champ type, afin qu’un SDK Claude natif puisse distinguer un refus de politique d’un échec générique de la passerelle.
Vous voulez le verdict exact avant de livrer une règle ? L’onglet Test de la console évalue la politique actuelle sur un texte d’échantillon sans appel en amont et sans quota — voir test & éval.

​
3. Pourquoi guardrail_blocked ne coûte aucun quota

Une requête bloquée est gratuite — elle ne débite jamais votre solde de crédit.
ÉtapeQuand le block se déclencheEffet sur le quota
inputAvant l’appel en amont, en avance sur la mesureRien n’est mesuré
outputAprès que le modèle a répondu, avant le retour de la réponseLe quota pré-consommé est remboursé
Donc un block d’entrée n’est rien facturé parce que la mesure n’a pas encore eu lieu, et un block de sortie inverse la réservation que la passerelle a placée avant la transmission. Dans les deux cas, l’appelant paie le block avec une 400, pas avec des crédits. Voir étape input et étape output.

​
4. Pourquoi guardrail_blocked saute le retry

L’erreur est marquée skip-retry. Le propre routage de la passerelle ne basculera pas cette requête vers un autre canal, parce que le block est une propriété de votre contenu et de votre politique — ré-exécuter le prompt identique ne ferait que bloquer à nouveau sur le canal suivant et gaspiller la tentative.
Ne mettez pas non plus guardrail_blocked dans la boucle de retry de votre client. Elle est déterministe : le même prompt contre la même politique bloque à chaque fois. Réessayer brûle de la latence pour un résultat qui ne peut pas changer. Traitez-la comme un rejet terminal — corrigez l’entrée, ou corrigez la politique.

​
5. La gérer dans le code client

Branchez sur le champ code et faites remonter un message utile à l’utilisateur final au lieu de réessayer. 
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()
La clé sk-orca-... ici est une clé de relais — elle ne porte que le trafic /v1/*. Vous ne modifiez jamais un guardrail avec elle ; rédiger et attacher une politique est une action de console / API de gestion sur votre session, et créer ou modifier un guardrail nécessite le rôle Developer+.

​
6. Confirmer et ajuster un block

Chaque règle qui se déclenche — block compris — atterrit dans le flux Matches de l’espace de travail avec son type, son action, son étape et une chaîne de détail. C’est là que vous confirmez quelle règle a rejeté un appel donné et triez les faux positifs.

Flux des correspondances

Voyez chaque block, mask et flag avec le type, l’action et l’étape. La sous-chaîne correspondante n’apparaît que lorsque Log raw content est activé.

Journalisation & confidentialité

Le contenu brut est désactivé par défaut — la posture conservatrice en matière de confidentialité. Activez-le par guardrail quand vous avez besoin de la sous-chaîne pour le triage.

Ajuster les faux positifs

Un faux positif est un signal d’ajustement, pas une raison de désactiver la règle. Marquez-le et resserrez le motif.

Versioning

Vous avez changé la politique et voulez l’annuler ? Faites le diff de deux versions et revenez en arrière comme une nouvelle version — l’historique n’est jamais muté.
Sur une réponse streaming, un block de sortie s’applique toujours : le scanner coupe le flux en plein vol avant que tout contenu bloqué n’atteigne le client. Le mask de sortie s’applique aussi in-band sur les flux — le scanner réécrit la correspondance dans le buffer roulant avant que le préfixe sûr ne soit émis. Voir couverture du streaming et règles stream-safe.

​
7. Liés