Saltar para o conteúdo principal
Quando um guardrail ou o firewall interrompe uma requisição, o OrcaRouter retorna um erro tipado sobre o qual seu código pode ramificar — não um 400 vago. Três códigos de segurança cobrem os casos que você verá: um prompt ou resposta filtrado, uma chamada de ferramenta negada e uma chamada de ferramenta retida para aprovação humana. Esta página é a referência desses códigos — o caso de uso de cada um, o status HTTP exato, o que ele custa a você, e a única regra que mais importa: a lógica de retry deve tratá-los como caso especial. Todos os três são marcados como skip-retry; reexecutar cegamente a mesma chamada apenas dispara o mesmo controle de novo.
Estes são códigos de enforcement — o gateway decidindo não encaminhar sua chamada. Eles são distintos de erros do provedor upstream (um 429 do modelo, um estouro de contexto) e de falhas de autenticação. Para saber por que uma requisição específica foi interrompida, veja Por que isto foi bloqueado?.

​
1. Os códigos de erro de segurança de llm em resumo

Todo bloqueio de segurança retorna HTTP 400 com um corpo de erro no formato da OpenAI (error.code é a string tipada abaixo). Nas rotas nativas do Claude (/v1/messages), o mesmo código viaja no formato de erro do Claude, então o roteamento do SDK é determinístico entre protocolos.
CódigoInterrompeCusto de cota
guardrail_blockedUm prompt ou resposta que atingiu uma regra blockNenhum
firewall_blockedUma chamada de ferramenta / anúncio negadoNenhum token de modelo
firewall_approval_pendingUma chamada de ferramenta retida para um revisor humanoNenhum token de modelo
Ramifique sobre error.code, nunca sobre a string da mensagem. As mensagens nomeiam o guardrail, a regra ou a ferramenta específica e vão mudar; os códigos são um contrato estável.

​
2. guardrail_blocked — um prompt ou resposta filtrado

Retornado quando uma regra de guardrail com a ação block dispara — uma palavra-chave na denylist, um acerto de regex, uma entidade de PII ou segredo que você escolheu bloquear em vez de mascarar, um veredito de llm_judge ou uma verificação de grounding falha. HTTP 400. A mensagem nomeia o guardrail e a regra que disparou.
Uma requisição bloqueada não custa cota. Um bloqueio em estágio de entrada dispara antes da medição, então nada é jamais cobrado. Um bloqueio em estágio de saída roda depois que o modelo responde, então o gateway reembolsa a cota pré-consumida antes de retornar o erro. De qualquer forma, você não paga nada por uma chamada bloqueada.
O veredito é uma propriedade do conteúdo, não do canal. Reexecutar o mesmo prompt — mesmo contra um modelo diferente — produz o mesmo bloqueio. Corrija a entrada (ou a política) em vez de fazer retry.
Regras de mask não retornam este código. Uma correspondência mascarada (ex.: jane@acme.com → [EMAIL]) é redigida no lugar e a chamada prossegue normalmente — você recebe um 200, apenas com o trecho sensível removido. Apenas a ação block expõe guardrail_blocked. (flag não altera nada no tráfego.)
{
  "error": {
    "type": "openai_error",
    "code": "guardrail_blocked",
    "message": "request blocked by guardrail \"pii-shield\": rule ssn (block)"
  }
}
Para os tipos de regra, estágios e ações por trás deste código, veja Guardrails. Para o envelope de erro campo a campo, veja Payloads de webhook & erro.

​
3. firewall_blocked — uma chamada de ferramenta negada

Retornado quando o firewall resolve um veredito deny para uma chamada de ferramenta — um comando shell destrutivo, um fetch no formato de SSRF, um destino de egress em uma deny list ou uma skill em modo block. Como o deny se manifesta depende da superfície de enforcement:

inbound / response / egress

HTTP 400 com error.code = firewall_blocked. O corpo carrega error.metadata estruturado (reason_code, factors de risco, risk_score) para que você possa explicar o bloqueio, não apenas vê-lo.

superfície mcp

Retornado como um erro de ferramenta (firewall deny: <reason>), não uma falha de transporte — de modo que o modelo vê a rejeição e pode escolher outra ferramenta, perguntar ao usuário, ou parar, em vez de quebrar a run.
sanitize não é um bloqueio. Um veredito sanitize redige substrings correspondentes dos argumentos da chamada de ferramenta e encaminha a chamada limpa — ele nunca retorna firewall_blocked. (A única exceção: na superfície inbound, onde ainda não há argumentos em tempo de chamada, sanitize escala para um 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"]
    }
  }
}
Em termos de cota, um bloqueio inbound dispara antes da chamada ao modelo upstream, então não custa nenhum token de modelo. Veja Glossário de vereditos para cada veredito, e Chamadas de ferramenta perigosas para as ameaças contra as quais este código defende.

​
4. firewall_approval_pending — retido para um humano

Retornado no instante em que uma chamada de ferramenta atinge um veredito pending_approval. Um portão com humano-no-loop não pode ser uma espera inline bloqueante, então o gateway retorna uma resposta retida imediatamente em vez de fazer long-polling. HTTP 400. O erro carrega o id de aprovação para que seu agente saiba qual hold resolver. Este é o único código a que você responde resolvendo e reenviando — não tratando-o como uma falha terminal:
1

Leia o id de aprovação do erro retido

O id é recuperável a partir do corpo do erro. Não faça retry da chamada ainda — um retry ingênuo apenas a retém de novo.
2

Aguarde uma decisão

Um revisor a resolve a partir do console (Developer+), ou seu sistema de aprovação recebe um callback de webhook assinado por HMAC. Seu agente consulta GET /api/v1/firewall/approvals/:id para obter o estado.
3

Reenvie com o token de aprovação

Uma vez aprovada, reemita a chamada original carregando o header de uso único X-OrcaRouter-Firewall-Approval. O gateway reconhece o id e deixa aquela única chamada passar.
As rotas de aprovação (/api/v1/firewall/approvals/*) rodam em uma chave com escopo de firewall-gateway, não na sua sessão de console. Veja Aprovação humana (HITL) para o loop completo e Payloads de webhook para a assinatura do callback.

​
5. Por que todos os três pulam o retry

A lógica padrão de retry do SDK assume que um 400 pode ter sucesso em uma segunda tentativa. Estes códigos quebram essa suposição — o bloqueio é determinístico, então um retry cego desperdiça um round trip e (para chamadas retidas) reenfileira silenciosamente uma aprovação.
A própria maquinaria interna de retry/fallback do OrcaRouter nunca retenta uma chamada que retorna um desses códigos contra outro canal. Espelhe isso no seu cliente: em um código de segurança, pare e aja sobre o veredito, não faça loop.
  • guardrail_blocked → corrija a entrada ou relaxe a política; exponha a recusa ao usuário. Não faça retry.
  • firewall_blocked → a ação é proibida; faça o agente escolher uma ferramenta diferente ou pedir ajuda. Não faça retry.
  • firewall_approval_pending → resolva o hold, depois reenvie uma vez com o header de aprovação (§4). Um retry sem o header o retém de novo.

​
6. Resumo de cota & billing

Um bloqueio de segurança nunca cobra de você a unidade de trabalho bloqueada.
CódigoQuando disparaResultado de billing
guardrail_blocked (input)Antes da chamada ao modeloNunca medido
guardrail_blocked (output)Depois que o modelo respondeCota pré-consumida reembolsada
firewall_blocked (inbound)Antes da chamada ao modeloNenhum token de modelo
firewall_approval_pendingAntes do dispatchNenhum token de modelo
Uma regra llm_judge ou grounding de um guardrail de fato chama um modelo para chegar ao seu veredito, e esses tokens de juiz são cobrados como uma sub-linha de juiz separada — mesmo quando o veredito é um bloqueio. Esse é o custo da verificação, não da requisição bloqueada em si.

​
7. Referências relacionadas

Por que isto foi bloqueado?

Rastreie um único bloqueio até a regra, superfície e motivo exatos que o produziram.

Glossário de vereditos

Cada veredito de firewall — allow, audit, deny, sanitize, pending_approval, cap_cost — e o que cada um emite.

Payloads de webhook & erro

O envelope de erro completo, os campos de error.metadata e a assinatura do callback de aprovação.

Modos de enforcement

Shadow, observe e enforce — quando um veredito realmente altera o tráfego.
Para os controles que produzem esses códigos, veja Guardrails e Firewall; para o vocabulário, veja o Glossário de conceitos.