Saltar al contenido principal
Cuando un guardrail rechaza una llamada, el gateway responde a tu aplicación con HTTP 400 y el código de error guardrail_blocked. Esta página es la referencia de aterrizaje para ese único error: cómo se ve el cuerpo, por qué se comporta como lo hace, y cómo manejarlo en el código del cliente. Para el motor de política detrás de él, ver Visión general de guardrails y la referencia completa.

​
1. Cuándo ves guardrail_blocked

Un guardrail es una lista ordenada de reglas que el gateway ejecuta contra la entrada de la solicitud y la salida del modelo. Cuando una regla cuya acción es block se dispara, la llamada es rechazada — el modelo upstream nunca se llama (etapa de entrada) o su respuesta se retiene (etapa de salida). El cliente recibe un 400 que lleva guardrail_blocked. Ninguna otra acción produce este error. mask redacta la coincidencia y deja pasar el texto saneado, flag registra una coincidencia sin cambiar el tráfico, y las acciones de modelado de prompt (annotate, spotlight) dejan continuar la llamada mientras añaden una nota o envuelven texto no confiable. De las cinco acciones, solo block rechaza. Ver Acciones.
guardrail_blocked es un rechazo de contenido (texto entra, texto sale). La denegación de política de herramientas complementaria es firewall_blocked del Agent Firewall — un error diferente con una forma diferente. Ver guardrails vs. firewall.

​
2. El cuerpo de la respuesta

El bloqueo se devuelve en el envoltorio de error estándar con forma de OpenAI del gateway. En un endpoint estilo OpenAI (/v1/chat/completions, /v1/responses): 
{
  "error": {
    "message": "request blocked by guardrail \"pii-shield\": pii(ssn)",
    "type": "orcarouter_api_error",
    "param": "",
    "code": "guardrail_blocked"
  }
}
Los campos sobre los que actúas:
El identificador de máquina estable. Ramifica sobre esto, no sobre la cadena del mensaje. Es el mismo valor en cada endpoint y nunca se localiza.
Legible por humanos. La forma es request blocked by guardrail "<name>": <detail>, donde <detail> resume el/los tipo(s) de regla que se disparó como <type>(<rule-detail>) — por ejemplo pii(pii: ssn) o keyword(matched 1 keyword(s)). Un bloqueo en la etapa de salida lee response blocked by guardrail "<name>": <detail>, así que el verbo te dice qué etapa rechazó la llamada. El mensaje pasa por el enmascarado de información sensible antes de salir del gateway, así que no esperes la subcadena coincidente en bruto aquí.
El tipo de error genérico del gateway en endpoints estilo OpenAI. La señal distintiva es code, no type.
En la superficie nativa de Anthropic (/v1/messages) el envoltorio tiene forma de Claude — {"error": {"type": ..., "message": ...}} — y guardrail_blocked aparece en el campo type, así que un SDK nativo de Claude puede distinguir una denegación de política de un fallo genérico del gateway.
¿Quieres el veredicto exacto antes de lanzar una regla? La pestaña Test de la consola evalúa la política actual sobre texto de muestra sin llamada upstream y sin cuota — ver pruebas y eval.

​
3. Por qué guardrail_blocked no cuesta cuota

Una solicitud bloqueada es gratis — nunca debita tu saldo de crédito.
EtapaCuándo se dispara el bloqueoEfecto en la cuota
inputAntes de la llamada upstream, por delante de la mediciónNada se mide
outputDespués de que el modelo responde, antes de que la respuesta regreseLa cuota preconsumida se reembolsa
Así que un bloqueo de entrada no se cobra nada porque la medición aún no ha ocurrido, y un bloqueo de salida revierte la retención que el gateway colocó antes de reenviar. En cualquier caso el llamador paga por el bloqueo con un 400, no con créditos. Ver etapa de entrada y etapa de salida.

​
4. Por qué guardrail_blocked se salta el reintento

El error está etiquetado como skip-retry. El propio enrutamiento del gateway no derivará esta solicitud a otro canal, porque el bloqueo es una propiedad de tu contenido y tu política — reejecutar el prompt idéntico simplemente volvería a bloquear en el siguiente canal y malgastaría el intento.
No pongas guardrail_blocked en el bucle de reintentos de tu cliente tampoco. Es determinista: el mismo prompt contra la misma política bloquea cada vez. Reintentar quema latencia por un resultado que no puede cambiar. Trátalo como un rechazo terminal — arregla la entrada, o arregla la política.

​
5. Manejarlo en el código del cliente

Ramifica sobre el campo code y presenta un mensaje útil al usuario final en vez de reintentar. 
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 clave sk-orca-... aquí es una clave de relay — solo lleva tráfico /v1/*. Nunca editas un guardrail con ella; crear y vincular política es una acción de consola / API de gestión sobre tu sesión, y crear o editar un guardrail requiere el rol Developer+.

​
6. Confirmar y afinar un bloqueo

Cada regla que se dispara — incluido block — aterriza en el feed Matches del espacio de trabajo con su tipo, acción, etapa y una cadena de detalle. Ahí es donde confirmas qué regla rechazó una llamada dada y triagas falsos positivos.

Feed de coincidencias

Ve cada block, mask y flag con tipo, acción y etapa. La subcadena coincidente aparece solo cuando Log raw content está activado.

Registro y privacidad

El contenido en bruto está apagado por defecto — la postura conservadora con la privacidad. Actívalo por guardrail cuando necesites la subcadena para triaje.

Afinar falsos positivos

Un falso positivo es una señal de ajuste, no una razón para deshabilitar la regla. Márcalo y acota el patrón.

Versionado

¿Cambiaste la política y quieres deshacerlo? Haz diff de dos versiones cualesquiera y revierte como una nueva versión — el historial nunca se muta.
En una respuesta con streaming, un block de salida todavía aplica: el escáner corta el stream en pleno vuelo antes de que cualquier contenido bloqueado llegue al cliente. Mask de salida también aplica en banda en streams — el escáner reescribe la coincidencia en el buffer rodante antes de que se emita el prefijo seguro. Ver cobertura de streaming y reglas seguras en streaming.

​
7. Relacionado