Saltar para o conteúdo principal
Quando um guardrail rejeita uma chamada, o gateway responde à sua aplicação com HTTP 400 e o código de erro guardrail_blocked. Esta página é a referência principal para esse único erro: como é o corpo, por que ele se comporta como se comporta, e como tratá-lo no código do cliente. Para o motor de política por trás dele, veja Visão geral dos guardrails e a referência completa.

​
1. Quando você vê guardrail_blocked

Um guardrail é uma lista ordenada de regras que o gateway executa contra a entrada da requisição e a saída do modelo. Quando uma regra cuja ação é block dispara, a chamada é rejeitada — o modelo upstream nunca é chamado (estágio de input) ou sua resposta é retida (estágio de output). O cliente recebe um 400 carregando guardrail_blocked. Nenhuma outra ação produz esse erro. mask redige a correspondência e deixa o texto sanitizado passar, flag registra um match sem mudar o tráfego, e as ações de modelagem de prompt (annotate, spotlight) deixam a chamada prosseguir enquanto adicionam uma nota ou envolvem texto não confiável. Das cinco ações, apenas block rejeita. Veja Ações.
guardrail_blocked é uma rejeição de conteúdo (texto entra, texto sai). A negação de política de ferramenta companheira é firewall_blocked do Agent Firewall — um erro diferente com um formato diferente. Veja guardrails vs. firewall.

​
2. O corpo da resposta

O block é retornado no envelope de erro padrão do gateway no formato OpenAI. Em um 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"
  }
}
Os campos sobre os quais você baseia sua lógica:
O identificador de máquina estável. Ramifique sobre este, não sobre a string da mensagem. É o mesmo valor em cada endpoint e nunca localizado.
Legível por humanos. A forma é request blocked by guardrail "<name>": <detail>, onde <detail> resume o(s) tipo(s) de regra que dispararam como <type>(<rule-detail>) — por exemplo pii(pii: ssn) ou keyword(matched 1 keyword(s)). Um block no estágio de output lê response blocked by guardrail "<name>": <detail>, então o verbo te diz qual estágio rejeitou a chamada. A mensagem passa por mascaramento de informações sensíveis antes de deixar o gateway, então não espere a substring correspondente bruta aqui.
O tipo de erro genérico do gateway em endpoints estilo OpenAI. O sinal distintivo é code, não type.
Na superfície nativa da Anthropic (/v1/messages) o envelope é no formato Claude — {"error": {"type": ..., "message": ...}} — e guardrail_blocked aparece no campo type, então um SDK nativo do Claude pode distinguir uma negação de política de uma falha genérica do gateway.
Quer o veredito exato antes de colocar uma regra em produção? A aba Test do console avalia a política atual sobre texto de amostra sem chamada upstream e sem cota — veja teste e eval.

​
3. Por que guardrail_blocked não custa cota

Uma requisição bloqueada é gratuita — ela nunca debita seu saldo de crédito.
EstágioQuando o block disparaEfeito na cota
inputAntes da chamada upstream, à frente da mediçãoNada é medido
outputDepois que o modelo responde, antes de a resposta retornarA cota pré-consumida é reembolsada
Então um block de input não cobra nada porque a medição ainda não aconteceu, e um block de output reverte o hold que o gateway colocou antes de encaminhar. De qualquer forma, o chamador paga pelo block com um 400, não com créditos. Veja estágio de input e estágio de output.

​
4. Por que guardrail_blocked pula a retry

O erro é marcado como skip-retry. O roteamento do próprio gateway não fará failover desta requisição para outro canal, porque o block é uma propriedade do seu conteúdo e da sua política — reexecutar o prompt idêntico apenas bloquearia de novo no próximo canal e desperdiçaria a tentativa.
Não coloque guardrail_blocked no loop de retry do seu cliente tampouco. Ele é determinístico: o mesmo prompt contra a mesma política bloqueia toda vez. Tentar de novo queima latência por um resultado que não pode mudar. Trate-o como uma rejeição terminal — corrija o input, ou corrija a política.

​
5. Tratando no código do cliente

Ramifique sobre o campo code e mostre uma mensagem útil ao usuário final em vez de tentar de novo. 
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()
A chave sk-orca-... aqui é uma chave de relay — ela só carrega tráfego /v1/*. Você nunca edita um guardrail com ela; escrever e vincular política é uma ação de console / API de gerenciamento na sua sessão, e criar ou editar um guardrail exige o papel Developer+.

​
6. Confirmando e ajustando um block

Toda regra que dispara — block incluído — cai no feed Matches do workspace com seu tipo, ação, estágio e uma string de detalhe. É ali que você confirma qual regra rejeitou uma dada chamada e faz a triagem de falsos positivos.

Feed de matches

Veja cada block, mask e flag com tipo, ação e estágio. A substring correspondente aparece apenas quando Log raw content está ligado.

Logging e privacidade

Conteúdo bruto está desligado por padrão — a postura conservadora de privacidade. Ligue-o por guardrail quando precisar da substring para triagem.

Ajustar falsos positivos

Um falso positivo é um sinal de ajuste, não um motivo para desabilitar a regra. Marque-o e estreite o padrão.

Versionamento

Mudou a política e quer desfazer? Faça o diff de quaisquer duas versões e reverta como uma nova versão — o histórico nunca é mutado.
Em uma resposta streaming, um block de output ainda se aplica: o scanner corta o stream em pleno voo antes que qualquer conteúdo bloqueado chegue ao cliente. O mask de output também se aplica in-band em streams — o scanner reescreve a correspondência no buffer rolante antes de o prefixo seguro ser emitido. Veja cobertura de streaming e regras stream-safe.

​
7. Relacionado