Saltar al contenido principal
Una solicitud devolvió HTTP 400 y tu agente se detuvo. Antes de que cambies cualquier código, el gateway ya te dijo qué pasó: el código de error nombra qué control se disparó, y uno de dos feeds nombra la regla exacta. Esta página es el flujo de búsqueda y rastreo — lee el código, abre el feed correcto, encuentra la regla. Si solo recuerdas una cosa: un 400 de un control de seguridad no es un bug en tu prompt. Es una política haciendo su trabajo. Tu trabajo es encontrar cuál política, luego decidir si arreglar la llamada o relajar la regla.

​
1. ¿Por qué se bloqueó mi solicitud de llm? — empieza por el código de error

Cada bloqueo de seguridad en el gateway alojado devuelve HTTP 400 con un code legible por máquina en el cuerpo de error con forma de OpenAI. Ese código es la primera bifurcación del camino — te dice qué plano de control depurar y qué feed abrir. 
{
  "error": {
    "message": "tool \"shell.exec\" blocked by firewall: destructive shell command",
    "code": "firewall_blocked",
    "type": "invalid_request_error"
  }
}

guardrail_blocked

Una regla de contenido de Guardrail se disparó en la entrada de tu solicitud o en la salida del modelo. Rastréala en el feed de Matches. Ve §2.

firewall_blocked

Una regla de Firewall denegó una llamada a herramienta. Rastréala en el feed de Events. Ve §3.

firewall_approval_pending

Una llamada a herramienta está retenida para aprobación humana — no denegada. Resuélvela, no la depures. Ve §4.
Los tres códigos son skip-retry: reejecutar la llamada idéntica enruta a la misma política y bloquea de nuevo. Reintentar es latencia desperdiciada — arregla la entrada o la regla en su lugar. La tabla completa de códigos vive en Códigos de error.

​
2. guardrail_blocked — encuentra la regla en Matches

guardrail_blocked significa que una política de contenido adjunta a tu clave (o el valor por defecto de tu espacio de trabajo) ejecutó una acción block contra la entrada de la solicitud o la salida del modelo. El mensaje de bloqueo nombra el guardrail y la regla, y la solicitud no te cuesta cuota — los bloqueos de entrada se disparan antes del medido; los bloqueos de salida reembolsan la cuota preconsumida. Rastréalo:
1

Abre el feed de Matches

En la consola, ve a la pestaña Matches en la página de Guardrails (GET /api/guardrail/match, Member). Cada regla que se dispara aterriza aquí — su RuleType, Action, Stage y una cadena Detail como pii: email, phone o matched 3 keyword(s).
2

Filtra al bloqueo

Filtra por action = block y la hora de tu solicitud. La fila coincidente te dice el tipo de regla (pii, regex, keyword, max_chars, llm_judge, grounding, external) y si se disparó en la etapa input o output.
3

Ve qué coincidió realmente

Por defecto el feed registra que una regla se disparó y su meta-cadena Detail — no la subcadena coincidente. Activa Log raw content en ese guardrail (está apagado por defecto, la postura conservadora con la privacidad) para capturar la cadena ofensora para el triaje. El interruptor no es retroactivo.
¿Un bloqueo que crees que es incorrecto? Abre la coincidencia y márcala como falso positivo (POST /api/guardrail/match/:id/mark-fp, Admin). Para probar el arreglo antes de lanzarlo, edita la regla y reejecuta la muestra en la pestaña Test del editor de guardrails — sin llamada upstream, sin cuota.

​
Un ejemplo concreto

Envías una respuesta de soporte que contiene el SSN de un cliente. Tu guardrail pii-shield tiene un override de entity_actions que bloquea en ssn: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "ssn"],
  "entity_actions": { "ssn": "block" }
}
El gateway devuelve 400 guardrail_blocked. El feed de Matches muestra RuleType: pii, Action: block, Stage: input, Detail: pii: ssn. El arreglo es una decisión de producto, no un cambio de código: relaja el override a mask (el modelo nunca ve el SSN, la llamada pasa), o mantén el bloqueo y elimina el SSN upstream. Ve Guardrails para la referencia completa de tipos de regla y entidades PII.

​
3. firewall_blocked — encuentra el veredicto en Events

firewall_blocked significa que una política de Firewall denegó una llamada a herramienta. En la superficie inbound se manifiesta como 400; a través del gateway MCP se manifiesta como un error de herramienta (firewall deny: <reason>) para que el modelo pueda reaccionar en vez de tumbarse. La metadata del error lleva el código de razón, los factores de riesgo y la puntuación. Rastréalo en el feed de Events (GET /api/workspace/firewall/events, Developer+) — el registro en bruto detrás de cada evaluación. Cada evento lleva un veredicto y la superficie en la que se vio:
VeredictoQué significa para tu bloqueo
denyUna regla (o el default_verdict) bloqueó la llamada. Este es tu firewall_blocked.
auditPermitido pero registrado — incluyendo un [shadow] “would deny” si la política está en modo shadow.
cap_costEl gasto acumulado de la ejecución cruzó un tope en centavos por regla; resuelve a un deny.
1

Filtra Events a la denegación

Filtra por verdict=deny, luego por tool, run_id o session_id para aislar la llamada exacta. El evento nombra la regla coincidente y la superficie — inbound, response, mcp o egress.
2

Lee la razón en la regla coincidente

La cadena de razón (p. ej. destructive shell command, egress host not allowed) te dice si la regla coincidió por el nombre de herramienta, una cláusula args_match o un destino de egress. El glosario de veredictos y la referencia de glob y JSONPath decodifican la coincidencia.
3

Confirma con el sandbox de Test

Reproduce la misma llamada a herramienta en la pestaña Test del Firewall (POST /api/workspace/firewall/test, Developer+) para ver el veredicto, la regla coincidente y la razón — nada despachado, nada registrado.
Un deny cap_cost no es un disparo erróneo de regla — tu ejecución de agente alcanzó el techo de gasto que estableciste. O la ejecución está en bucle (revisa el resumen de Runs y el feed de anomalías en busca de un retry_loop) o el tope es genuinamente demasiado bajo para la tarea. Sube el tope deliberadamente, no solo reintentes.

​
4. firewall_approval_pending — está retenida, no denegada

firewall_approval_pending es el único 400 que no deberías tratar como un bloqueo. Un veredicto pending_approval retuvo la llamada a herramienta para un humano; el cuerpo del error lleva un id de aprobación. La llamada no ha fallado — está esperando.
  1. Un revisor la resuelve — desde la consola (Developer+) o vía tu propio callback de webhook HMAC (POST /api/v1/firewall/approvals/:id/callback).
  2. Tu agente hace polling de GET /api/v1/firewall/approvals/:id (token de gateway) sobre el id del error.
  3. Una vez aprobado, reenvía la llamada original con la cabecera de un solo uso X-OrcaRouter-Firewall-Approval, y el gateway la deja pasar esa única vez.
Ve Firewall → Aprobación humana para el bucle HITL completo.

​
5. ¿No es un bloqueo de seguridad? Descarta la clave primero

No todo 400 es un veredicto de guardrail o firewall. Antes de que te pongas a bucear en los feeds, descarta las restricciones de la clave — estas rechazan antes de que se ejecute cualquier política y no llevan los códigos de seguridad de arriba:
La allow-list de model_limits de la clave no incluye el modelo solicitado. Las solicitudes de un modelo fuera de la lista se rechazan de entrada. Añade el modelo a la clave o llama a uno permitido.
La clave tiene una allow-list allow_ips y la solicitud vino de una dirección fuera de ella. Añade la IP / CIDR del llamante o llama desde una red permitida.
El techo credit_limit_usd de la clave está agotado (0 significa ilimitado). Sube el tope o rota a una clave con margen.
Los hooks del gateway (evaluate, despacho MCP) requieren una clave con is_firewall_gateway=true. Una clave de relay normal obtiene 403. Acuña una clave con alcance de gateway de firewall para esas rutas.

​
6. El flujo de triaje de dos minutos

Bloqueo en texto de prompt o respuesta

El código es guardrail_blocked → abre Matches, filtra action=block, lee el Stage + Detail. Arregla el contenido o la regla; pruébalo en la pestaña Test del guardrail.

Bloqueo en una llamada a herramienta

El código es firewall_blocked → abre Events, filtra verdict=deny, lee la superficie + razón. Arregla la llamada o la regla; pruébalo en la pestaña Test del firewall.

La llamada está retenida

El código es firewall_approval_pending → haz polling del id de aprobación y reenvía con la cabecera de aprobación. Nada que depurar.

Ninguno de los anteriores

Sin código de seguridad → revisa la clave: model_limits, allow_ips, credit_limit_usd, o 403 por un alcance de gateway faltante.

​
7. Referencias relacionadas

Códigos de error

La tabla completa de códigos — cada bloqueo, retención y rechazo que el gateway puede devolver.

Glosario de veredictos

Qué significa cada veredicto del firewall y cuándo resuelve a un deny.

Glob y JSONPath

Decodifica el tool_name_glob y el args_match que coincidieron con tu llamada.

Guardrails vs Firewall

Qué plano se disparó — examen de texto o gobierno de acciones.
Para los controles en sí, ve Guardrails y Firewall; para las amenazas que detienen, empieza en el modelo de amenazas.