Vai al contenuto principale
Quando un guardrail rifiuta una chiamata, il gateway risponde alla tua applicazione con HTTP 400 e il codice di errore guardrail_blocked. Questa pagina è il riferimento di destinazione per quell’unico errore: com’è fatto il corpo, perché si comporta nel modo in cui lo fa, e come gestirlo nel codice client. Per il motore di policy dietro di esso, vedi Panoramica dei Guardrails e il riferimento completo.

​
1. Quando vedi guardrail_blocked

Un guardrail è un elenco ordinato di regole che il gateway esegue sull’input della richiesta e sull’output del modello. Quando una regola la cui azione è block scatta, la chiamata viene rifiutata — il modello upstream non viene mai chiamato (stage di input) o la sua risposta viene trattenuta (stage di output). Il client riceve un 400 che porta guardrail_blocked. Nessun’altra azione produce questo errore. mask redige il match e lascia passare il testo sanitizzato, flag registra un match senza cambiare il traffico, e le azioni di prompt-shaping (annotate, spotlight) lasciano procedere la chiamata aggiungendo una nota o avvolgendo il testo non attendibile. Delle cinque azioni, solo block rifiuta. Vedi Azioni.
guardrail_blocked è un rifiuto di contenuto (testo in, testo out). La negazione di policy di tool complementare è firewall_blocked dall’ Agent Firewall — un errore diverso con una forma diversa. Vedi guardrails vs. firewall.

​
2. Il corpo della risposta

Il block è restituito nell’envelope di errore standard OpenAI-shaped del gateway. Su un endpoint in stile OpenAI (/v1/chat/completions, /v1/responses): 
{
  "error": {
    "message": "request blocked by guardrail \"pii-shield\": pii(ssn)",
    "type": "orcarouter_api_error",
    "param": "",
    "code": "guardrail_blocked"
  }
}
I campi su cui ti basi:
L’identificatore macchina stabile. Ramifica su questo, non sulla stringa del messaggio. È lo stesso valore su ogni endpoint e non viene mai localizzato.
Leggibile dall’uomo. La forma è request blocked by guardrail "<name>": <detail>, dove <detail> riassume i tipi di regola che hanno scattato come <type>(<rule-detail>) — per esempio pii(pii: ssn) o keyword(matched 1 keyword(s)). Un block nello stage di output legge response blocked by guardrail "<name>": <detail>, quindi il verbo ti dice quale stage ha rifiutato la chiamata. Il messaggio passa attraverso il masking delle informazioni sensibili prima di lasciare il gateway, quindi non aspettarti qui la sottostringa grezza corrispondente.
Il tipo di errore generico del gateway sugli endpoint in stile OpenAI. Il segnale distintivo è code, non type.
Sulla superficie nativa Anthropic (/v1/messages) l’envelope è Claude-shaped — {"error": {"type": ..., "message": ...}} — e guardrail_blocked emerge nel campo type, così un SDK Claude nativo può distinguere una negazione di policy da un fallimento generico del gateway.
Vuoi il verdetto esatto prima di mettere in produzione una regola? La tab Test della console valuta la policy corrente su testo di esempio senza chiamata upstream e senza quota — vedi testing ed eval.

​
3. Perché guardrail_blocked non costa quota

Una richiesta bloccata è gratuita — non addebita mai il tuo saldo di credito.
StageQuando scatta il blockEffetto sulla quota
inputPrima della chiamata upstream, prima della misurazioneNulla viene misurato
outputDopo che il modello risponde, prima che la risposta torniLa quota pre-consumata viene rimborsata
Quindi un block di input non addebita nulla perché la misurazione non è ancora avvenuta, e un block di output inverte il blocco che il gateway aveva posto prima di inoltrare. In entrambi i casi il chiamante paga per il block con un 400, non con crediti. Vedi stage di input e stage di output.

​
4. Perché guardrail_blocked salta il retry

L’errore è etichettato skip-retry. Il routing del gateway stesso non farà il failover di questa richiesta verso un altro canale, perché il block è una proprietà del tuo contenuto e della tua policy — rieseguire il prompt identico si limiterebbe a bloccarlo di nuovo sul canale successivo e sprecherebbe il tentativo.
Non mettere guardrail_blocked nemmeno nel loop di retry del tuo client. È deterministico: lo stesso prompt contro la stessa policy blocca ogni volta. Il retry brucia latenza per un esito che non può cambiare. Trattalo come un rifiuto terminale — correggi l’input, o correggi la policy.

​
5. Gestirlo nel codice client

Ramifica sul campo code e mostra un messaggio utile all’utente finale invece di riprovare. 
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()
La chiave sk-orca-... qui è una chiave di relay — porta solo traffico /v1/*. Non modifichi mai un guardrail con essa; scrivere e collegare la policy è un’azione di console / management-API sulla tua sessione, e creare o modificare un guardrail richiede il ruolo Developer+.

​
6. Confermare e mettere a punto un block

Ogni regola che scatta — block incluso — atterra nel feed Matches del workspace con il suo type, action, stage e una stringa di detail. È lì che confermi quale regola ha rifiutato una data chiamata e fai il triage dei falsi positivi.

Feed dei match

Vedi ogni block, mask e flag con type, action e stage. La sottostringa corrispondente appare solo quando Log raw content è attivo.

Logging e privacy

Il contenuto grezzo è disattivato per default — la postura conservativa sulla privacy. Attivalo per ciascun guardrail quando ti serve la sottostringa per il triage.

Tuning dei falsi positivi

Un falso positivo è un segnale di tuning, non un motivo per disabilitare la regola. Segnalalo e restringi il pattern.

Versioning

Hai modificato la policy e vuoi annullarlo? Confronta due versioni qualsiasi e ripristina come nuova versione — la cronologia non viene mai mutata.
Su una risposta in streaming, un block di output si applica comunque: lo scanner interrompe lo stream a metà prima che qualsiasi contenuto bloccato raggiunga il client. Il mask di output si applica anch’esso in-band sugli stream — lo scanner riscrive il match nel buffer scorrevole prima che il prefisso sicuro venga emesso. Vedi streaming coverage e regole stream-safe.

​
7. Correlati