Saltar al contenido principal
Cuando un guardrail o el firewall detiene una solicitud, OrcaRouter devuelve un error tipado sobre el que tu código puede ramificar — no un 400 impreciso. Tres códigos de seguridad cubren los casos que verás: un prompt o respuesta examinado, una llamada a herramienta denegada y una llamada a herramienta retenida para aprobación humana. Esta página es la referencia de esos códigos — el caso de uso de cada uno, el estado HTTP exacto, lo que te cuesta y la única regla que más importa: la lógica de reintento debe tratarlos como caso especial. Los tres están marcados como skip-retry; reejecutar a ciegas la misma llamada simplemente vuelve a disparar el mismo control.
Estos son códigos de aplicación — el gateway decidiendo no reenviar tu llamada. Son distintos de los errores del proveedor upstream (un 429 del modelo, un desbordamiento de contexto) y de los fallos de autenticación. Para saber por qué una solicitud específica fue detenida, ve ¿Por qué se bloqueó esto?.

​
1. Los códigos de error de seguridad de llm de un vistazo

Cada bloqueo de seguridad devuelve HTTP 400 con un cuerpo de error con forma de OpenAI (error.code es la cadena tipada de abajo). En las rutas nativas de Claude (/v1/messages) el mismo código viaja en la forma de error de Claude, así que el enrutamiento del SDK es determinista entre protocolos.
CódigoDetieneCoste de cuota
guardrail_blockedUn prompt o respuesta que golpeó una regla blockNinguno
firewall_blockedUna llamada a herramienta / anuncio denegadoSin tokens de modelo
firewall_approval_pendingUna llamada a herramienta retenida para un revisor humanoSin tokens de modelo
Ramifica sobre error.code, nunca sobre la cadena del mensaje. Los mensajes nombran el guardrail, la regla o la herramienta específicos y cambiarán; los códigos son un contrato estable.

​
2. guardrail_blocked — un prompt o respuesta examinado

Devuelto cuando una regla de guardrail con la acción block se dispara — una palabra clave en lista de denegación, una coincidencia de regex, una entidad de PII o secreto que elegiste bloquear en vez de enmascarar, un veredicto de llm_judge o una verificación de grounding fallida. HTTP 400. El mensaje nombra el guardrail y la regla que se disparó.
Una solicitud bloqueada no cuesta cuota. Un bloqueo en etapa de entrada se dispara antes del medido, así que nunca se factura nada. Un bloqueo en etapa de salida se ejecuta después de que el modelo responde, así que el gateway reembolsa la cuota preconsumida antes de devolver el error. En cualquier caso no pagas nada por una llamada bloqueada.
El veredicto es una propiedad del contenido, no del canal. Reejecutar el mismo prompt — incluso contra un modelo diferente — produce el mismo bloqueo. Arregla la entrada (o la política) en vez de reintentar.
Las reglas mask no devuelven este código. Una coincidencia enmascarada (p. ej. jane@acme.com → [EMAIL]) se redacta en su sitio y la llamada procede con normalidad — obtienes un 200, solo que con el fragmento sensible eliminado. Solo la acción block expone guardrail_blocked. (flag no cambia nada del tráfico en absoluto.)
{
  "error": {
    "type": "openai_error",
    "code": "guardrail_blocked",
    "message": "request blocked by guardrail \"pii-shield\": rule ssn (block)"
  }
}
Para los tipos de regla, etapas y acciones detrás de este código, ve Guardrails. Para el sobre de error campo por campo, ve Payloads de webhook y error.

​
3. firewall_blocked — una llamada a herramienta denegada

Devuelto cuando el firewall resuelve un veredicto deny para una llamada a herramienta — un comando shell destructivo, un fetch con forma de SSRF, un destino de egress en una lista de denegación, o una skill en modo block. Cómo se manifiesta el deny depende de la superficie de aplicación:

inbound / response / egress

HTTP 400 con error.code = firewall_blocked. El cuerpo lleva error.metadata estructurada (reason_code, factors de riesgo, risk_score) para que puedas explicar el bloqueo, no solo verlo.

superficie mcp

Devuelto como un error de herramienta (firewall deny: <reason>), no un fallo de transporte — así que el modelo ve el rechazo y puede elegir otra herramienta, preguntar al usuario o detenerse, en vez de tumbar la ejecución.
sanitize no es un bloqueo. Un veredicto sanitize redacta las subcadenas coincidentes de los argumentos de la llamada a herramienta y reenvía la llamada limpia — nunca devuelve firewall_blocked. (La única excepción: en la superficie inbound, donde aún no hay argumentos en tiempo de llamada, sanitize escala a 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"]
    }
  }
}
En cuanto a cuota, un bloqueo inbound se dispara antes de la llamada al modelo upstream, así que no cuesta tokens de modelo. Ve Glosario de veredictos para cada veredicto, y Llamadas a herramienta peligrosas para las amenazas contra las que defiende este código.

​
4. firewall_approval_pending — retenido para un humano

Devuelto en el instante en que una llamada a herramienta golpea un veredicto pending_approval. Una compuerta human-in-the-loop no puede ser una espera en línea bloqueante, así que el gateway devuelve una respuesta retenida de inmediato en vez de hacer long-polling. HTTP 400. El error lleva el id de aprobación para que tu agente sepa qué retención resolver. Este es el único código al que respondes resolviendo y reenviando — no tratándolo como un fallo terminal:
1

Lee el id de aprobación del error retenido

El id es recuperable del cuerpo del error. No reintentes la llamada todavía — un reintento ingenuo simplemente vuelve a retener.
2

Espera una decisión

Un revisor la resuelve desde la consola (Developer+), o tu sistema de aprobación recibe un callback de webhook firmado con HMAC. Tu agente hace polling de GET /api/v1/firewall/approvals/:id para el estado.
3

Reenvía con el token de aprobación

Una vez aprobado, reemite la llamada original llevando la cabecera de un solo uso X-OrcaRouter-Firewall-Approval. El gateway reconoce el id y deja pasar esa única llamada.
Las rutas de aprobación (/api/v1/firewall/approvals/*) se ejecutan sobre una clave con alcance de gateway de firewall, no tu sesión de consola. Ve Aprobación humana (HITL) para el bucle completo y Payloads de webhook para la firma del callback.

​
5. Por qué los tres omiten el reintento

La lógica estándar de reintento del SDK asume que un 400 podría tener éxito en un segundo intento. Estos códigos rompen esa suposición — el bloqueo es determinista, así que un reintento a ciegas desperdicia un viaje de ida y vuelta y (para las llamadas retenidas) reencola silenciosamente una aprobación.
La propia maquinaria interna de reintento/fallback de OrcaRouter nunca reintenta una llamada que devuelve uno de estos códigos contra otro canal. Refleja eso en tu cliente: ante un código de seguridad, detente y actúa sobre el veredicto, no hagas bucle.
  • guardrail_blocked → arregla la entrada o relaja la política; expón el rechazo al usuario. No reintentes.
  • firewall_blocked → la acción está prohibida; haz que el agente elija una herramienta diferente o pida ayuda. No reintentes.
  • firewall_approval_pending → resuelve la retención, luego reenvía una vez con la cabecera de aprobación (§4). Un reintento sin la cabecera vuelve a retener.

​
6. Resumen de cuota y facturación

Un bloqueo de seguridad nunca te factura la unidad de trabajo bloqueada.
CódigoCuándo se disparaResultado de facturación
guardrail_blocked (input)Antes de la llamada al modeloNunca medido
guardrail_blocked (output)Después de que el modelo respondeCuota preconsumida reembolsada
firewall_blocked (inbound)Antes de la llamada al modeloSin tokens de modelo
firewall_approval_pendingAntes del despachoSin tokens de modelo
Una regla llm_judge o grounding de un guardrail sí llama a un modelo para alcanzar su veredicto, y esos tokens del juez se facturan como una sub-línea de juez separada — incluso cuando el veredicto es un bloqueo. Ese es el coste de la verificación, no de la solicitud bloqueada en sí.

​
7. Referencias relacionadas

¿Por qué se bloqueó esto?

Rastrea un único bloqueo hasta la regla, superficie y razón exactas que lo produjeron.

Glosario de veredictos

Cada veredicto del firewall — allow, audit, deny, sanitize, pending_approval, cap_cost — y lo que emite cada uno.

Payloads de webhook y error

El sobre de error completo, los campos error.metadata y la firma del callback de aprobación.

Modos de aplicación

Shadow, observe y enforce — cuándo un veredicto realmente cambia el tráfico.
Para los controles que producen estos códigos, ve Guardrails y Firewall; para el vocabulario, ve el Glosario de conceptos.