Saltar para o conteúdo principal
Uma requisição retornou HTTP 400 e seu agente travou. Antes de você mudar qualquer código, o gateway já lhe disse o que aconteceu: o código de erro nomeia qual controle disparou, e um de dois feeds nomeia a regra exata. Esta página é o fluxo de consultar-e-rastrear — leia o código, abra o feed certo, encontre a regra. Se você só lembrar de uma coisa: um 400 de um controle de segurança não é um bug no seu prompt. É uma política fazendo seu trabalho. Sua tarefa é encontrar qual política, depois decidir se corrige a chamada ou relaxa a regra.

​
1. Por que minha requisição de llm foi bloqueada? — comece pelo código de erro

Todo bloqueio de segurança no gateway hospedado retorna HTTP 400 com um code legível por máquina no corpo de erro no formato da OpenAI. Esse código é a primeira bifurcação no caminho — ele lhe diz qual plano de controle depurar e qual feed abrir. 
{
  "error": {
    "message": "tool \"shell.exec\" blocked by firewall: destructive shell command",
    "code": "firewall_blocked",
    "type": "invalid_request_error"
  }
}

guardrail_blocked

Uma regra de conteúdo de Guardrail disparou na entrada da sua requisição ou na saída do modelo. Rastreie-a no feed de Matches. Veja §2.

firewall_blocked

Uma regra de Firewall negou uma chamada de ferramenta. Rastreie-a no feed de Events. Veja §3.

firewall_approval_pending

Uma chamada de ferramenta está retida para aprovação humana — não negada. Resolva-a, não a depure. Veja §4.
Todos os três códigos são skip-retry: reexecutar a chamada idêntica roteia para a mesma política e bloqueia de novo. Fazer retry é latência desperdiçada — corrija a entrada ou a regra em vez disso. A tabela completa de códigos vive em Códigos de erro.

​
2. guardrail_blocked — encontre a regra em Matches

guardrail_blocked significa que uma política de conteúdo vinculada à sua chave (ou ao padrão do seu workspace) rodou uma ação block contra a entrada da requisição ou a saída do modelo. A mensagem de bloqueio nomeia o guardrail e a regra, e a requisição não custa cota a você — bloqueios de entrada disparam antes da medição; bloqueios de saída reembolsam a cota pré-consumida. Rastreie:
1

Abra o feed de Matches

No console, vá até a aba Matches na página de Guardrails (GET /api/guardrail/match, Member). Toda regra que dispara cai aqui — seu RuleType, Action, Stage e uma string Detail como pii: email, phone ou matched 3 keyword(s).
2

Filtre pelo bloqueio

Filtre por action = block e o horário da sua requisição. A linha correspondente lhe diz o tipo de regra (pii, regex, keyword, max_chars, llm_judge, grounding, external) e se disparou no estágio input ou output.
3

Veja o que ela realmente correspondeu

Por padrão, o feed registra que uma regra disparou e sua meta-string Detail — não a substring correspondente. Ligue Log raw content naquele guardrail (está desligado por padrão, a postura conservadora de privacidade) para capturar a string ofensora para triagem. O interruptor é não-retroativo.
Um bloqueio que você acredita estar errado? Abra o match e marque-o como falso positivo (POST /api/guardrail/match/:id/mark-fp, Admin). Para provar a correção antes de aplicá-la, edite a regra e reexecute a amostra na aba Test do editor de guardrail — sem chamada upstream, sem cota.

​
Um exemplo concreto

Você envia uma resposta de suporte que contém o SSN de um cliente. Seu guardrail pii-shield tem um override de entity_actions que bloqueia em ssn: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "ssn"],
  "entity_actions": { "ssn": "block" }
}
O gateway retorna 400 guardrail_blocked. O feed de Matches mostra RuleType: pii, Action: block, Stage: input, Detail: pii: ssn. A correção é uma decisão de produto, não uma mudança de código: relaxe o override para mask (o modelo nunca vê o SSN, a chamada passa), ou mantenha o bloqueio e remova o SSN upstream. Veja Guardrails para a referência completa de tipos de regra e entidades de PII.

​
3. firewall_blocked — encontre o veredito em Events

firewall_blocked significa que uma política de Firewall negou uma chamada de ferramenta. Na superfície inbound ela se manifesta como 400; através do gateway MCP ela se manifesta como um erro de ferramenta (firewall deny: <reason>) para que o modelo possa reagir em vez de quebrar. O metadata do erro carrega o código de motivo, fatores de risco e score. Rastreie no feed de Events (GET /api/workspace/firewall/events, Developer+) — o registro bruto por trás de cada avaliação. Cada evento carrega um veredito e a superfície na qual foi visto:
VereditoO que significa para o seu bloqueio
denyUma regra (ou o default_verdict) bloqueou a chamada. Este é o seu firewall_blocked.
auditPermitido mas registrado — incluindo um [shadow] “would deny” se a política está em shadow mode.
cap_costO gasto acumulado da run cruzou um limite por regra em centavos; resolve para um deny.
1

Filtre Events para a negação

Filtre por verdict=deny, depois por tool, run_id ou session_id para isolar a chamada exata. O evento nomeia a regra correspondente e a superfície — inbound, response, mcp ou egress.
2

Leia o motivo na regra correspondente

A string de motivo (ex.: destructive shell command, egress host not allowed) lhe diz se a regra correspondeu pelo nome da ferramenta, por uma cláusula args_match ou por um destino de egress. O glossário de vereditos e a referência de glob & JSONPath decodificam a correspondência.
3

Confirme com o sandbox de Test

Reproduza a mesma chamada de ferramenta na aba Test do Firewall (POST /api/workspace/firewall/test, Developer+) para ver o veredito, a regra correspondente e o motivo — nada despachado, nada registrado.
Um deny cap_cost não é uma regra disparando errado — sua run de agente atingiu o teto de gasto que você definiu. Ou a run está em loop (verifique o rollup de Runs e o feed de anomalias para um retry_loop) ou o limite está genuinamente baixo demais para a tarefa. Eleve o limite deliberadamente, não apenas faça retry.

​
4. firewall_approval_pending — está retida, não negada

firewall_approval_pending é o único 400 que você não deve tratar como um bloqueio. Um veredito pending_approval reteve a chamada de ferramenta para um humano; o corpo do erro carrega um id de aprovação. A chamada não falhou — ela está esperando.
  1. Um revisor a resolve — a partir do console (Developer+) ou via seu próprio callback de webhook HMAC (POST /api/v1/firewall/approvals/:id/callback).
  2. Seu agente consulta GET /api/v1/firewall/approvals/:id (token de gateway) com o id do erro.
  3. Uma vez aprovada, reenvie a chamada original com o header de uso único X-OrcaRouter-Firewall-Approval, e o gateway a deixa passar aquela única vez.
Veja Firewall → Aprovação humana para o loop completo de HITL.

​
5. Não é um bloqueio de segurança? Descarte a chave primeiro

Nem todo 400 é um veredito de guardrail ou firewall. Antes de mergulhar nos feeds, descarte as restrições de chave — estas rejeitam antes de qualquer política rodar e não carregam os códigos de segurança acima:
A allow-list model_limits da chave não inclui o modelo requisitado. Requisições para um modelo fora da lista são rejeitadas de antemão. Adicione o modelo à chave ou chame um que esteja permitido.
A chave tem uma allow-list allow_ips e a requisição veio de um endereço fora dela. Adicione o IP / CIDR do chamador ou chame de uma rede permitida.
O teto credit_limit_usd da chave foi esgotado (0 significa ilimitado). Eleve o limite ou alterne para uma chave com folga.
Os hooks do gateway (evaluate, dispatch de MCP) exigem uma chave com is_firewall_gateway=true. Uma chave de relay normal recebe 403. Cunhe uma chave com escopo de firewall-gateway para essas rotas.

​
6. O fluxo de triagem de dois minutos

Bloqueio em texto de prompt ou resposta

O código é guardrail_blocked → abra Matches, filtre action=block, leia o Stage + Detail. Corrija o conteúdo ou a regra; prove na aba Test do guardrail.

Bloqueio em uma chamada de ferramenta

O código é firewall_blocked → abra Events, filtre verdict=deny, leia a superfície + motivo. Corrija a chamada ou a regra; prove na aba Test do firewall.

A chamada está retida

O código é firewall_approval_pending → consulte o id de aprovação e reenvie com o header de aprovação. Nada a depurar.

Nenhum dos acima

Sem código de segurança → verifique a chave: model_limits, allow_ips, credit_limit_usd, ou 403 por um escopo de gateway ausente.

​
7. Referências relacionadas

Códigos de erro

A tabela completa de códigos — todo bloqueio, hold e rejeição que o gateway pode retornar.

Glossário de vereditos

O que cada veredito de firewall significa e quando resolve para um deny.

Glob & JSONPath

Decodifique o tool_name_glob e o args_match que corresponderam à sua chamada.

Guardrails vs Firewall

Qual plano disparou — filtragem de texto ou governança de ações.
Para os controles em si, veja Guardrails e Firewall; para as ameaças que eles interrompem, comece pelo modelo de ameaças.