Vai al contenuto principale
Una richiesta ha restituito HTTP 400 e il tuo agent si è bloccato. Prima di modificare qualsiasi codice, il gateway ti ha già detto cos’è successo: il codice di errore nomina quale controllo è scattato, e uno di due feed nomina la regola esatta. Questa pagina è il flusso di lookup-e-trace — leggi il codice, apri il feed giusto, trova la regola. Se ricordi una sola cosa: un 400 da un controllo di sicurezza non è un bug nel tuo prompt. È una policy che fa il suo lavoro. Il tuo compito è trovare quale policy, poi decidere se correggere la chiamata o allentare la regola.

​
1. Perché la mia richiesta llm è stata bloccata? — parti dal codice di errore

Ogni block di sicurezza sul gateway hosted restituisce HTTP 400 con un code machine-readable nel corpo di errore in forma OpenAI. Quel codice è il primo bivio sulla strada — ti dice quale control plane debuggare e quale feed aprire. 
{
  "error": {
    "message": "tool \"shell.exec\" blocked by firewall: destructive shell command",
    "code": "firewall_blocked",
    "type": "invalid_request_error"
  }
}

guardrail_blocked

Una regola di contenuto di un Guardrail è scattata sull’input della tua richiesta o sull’output del modello. Risalila nel feed Matches. Vedi §2.

firewall_blocked

Una regola del Firewall ha negato una chiamata a tool. Risalila nel feed Events. Vedi §3.

firewall_approval_pending

Una chiamata a tool è in attesa di approvazione umana — non negata. Risolvila, non debuggarla. Vedi §4.
Tutti e tre i codici sono skip-retry: ri-eseguire la chiamata identica instrada sulla stessa policy e blocca di nuovo. Il retry è latenza sprecata — correggi l’input o la regola invece. La tabella completa dei codici vive in Codici di errore.

​
2. guardrail_blocked — trova la regola in Matches

guardrail_blocked significa che una policy di contenuto collegata alla tua chiave (o il default del tuo workspace) ha eseguito un’azione block contro l’input della richiesta o l’output del modello. Il messaggio di block nomina il guardrail e la regola, e la richiesta non ti costa quota — i block in input scattano prima del metering; i block in output rimborsano la quota pre-consumata. Risalila:
1

Apri il feed Matches

Nella console, vai alla tab Matches sulla pagina Guardrails (GET /api/guardrail/match, Member). Ogni regola che scatta finisce qui — il suo RuleType, Action, Stage e una stringa Detail come pii: email, phone o matched 3 keyword(s).
2

Filtra fino al block

Filtra per action = block e per l’orario della tua richiesta. La riga corrispondente ti dice il tipo di regola (pii, regex, keyword, max_chars, llm_judge, grounding, external) e se è scattata sulla fase input o output.
3

Vedi cosa ha effettivamente corrisposto

Per default il feed registra che una regola è scattata e la sua meta-stringa Detail — non la sottostringa corrispondente. Attiva Log raw content su quel guardrail (è disattivato di default, la postura conservativa sulla privacy) per catturare la stringa incriminata ai fini del triage. L’interruttore non è retroattivo.
Un block che credi sbagliato? Apri il match e marcalo come falso positivo (POST /api/guardrail/match/:id/mark-fp, Admin). Per provare la correzione prima di rilasciarla, modifica la regola e ri-esegui il campione nella tab Test dell’editor del guardrail — nessuna chiamata upstream, nessuna quota.

​
Un esempio concreto

Invii una risposta di supporto che contiene un SSN di un cliente. Il tuo guardrail pii-shield ha un override entity_actions che blocca su ssn: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "ssn"],
  "entity_actions": { "ssn": "block" }
}
Il gateway restituisce 400 guardrail_blocked. Il feed Matches mostra RuleType: pii, Action: block, Stage: input, Detail: pii: ssn. La correzione è una decisione di prodotto, non una modifica al codice: allenta l’override a mask (il modello non vede mai l’SSN, la chiamata passa), o mantieni il block e rimuovi l’SSN a monte. Vedi Guardrails per il riferimento completo su tipi di regola ed entità PII.

​
3. firewall_blocked — trova il verdetto in Events

firewall_blocked significa che una policy del Firewall ha negato una chiamata a tool. Sulla superficie inbound emerge come 400; attraverso il gateway MCP emerge come errore di tool (firewall deny: <reason>) così il modello può reagire invece di andare in crash. Il metadata dell’errore porta il codice di motivazione, i fattori di rischio e il punteggio. Risalila nel feed Events (GET /api/workspace/firewall/events, Developer+) — il record grezzo dietro ogni valutazione. Ogni evento porta un verdetto e la superficie su cui è stato visto:
VerdettoCosa significa per il tuo block
denyUna regola (o il default_verdict) ha bloccato la chiamata. Questo è il tuo firewall_blocked.
auditConsentito ma loggato — incluso un [shadow] “would deny” se la policy è in shadow mode.
cap_costLa spesa accumulata dell’esecuzione ha superato un tetto in centesimi per regola; si risolve in un deny.
1

Filtra Events fino al deny

Filtra per verdict=deny, poi per tool, run_id o session_id per isolare la chiamata esatta. L’evento nomina la regola corrispondente e la superficie — inbound, response, mcp o egress.
2

Leggi la motivazione sulla regola corrispondente

La stringa di motivazione (es. destructive shell command, egress host not allowed) ti dice se la regola ha corrisposto sul nome del tool, una clausola args_match o una destinazione di egress. Il glossario dei verdetti e il riferimento glob e JSONPath decodificano il matching.
3

Conferma con la sandbox Test

Riproduci la stessa chiamata a tool nella tab Test del Firewall (POST /api/workspace/firewall/test, Developer+) per vedere il verdetto, la regola corrispondente e la motivazione — nulla dispatchato, nulla loggato.
Un deny cap_cost non è un malfunzionamento di una regola — la tua esecuzione dell’agent ha raggiunto il tetto di spesa che hai impostato. O l’esecuzione sta ciclando (controlla il rollup Runs e il feed delle anomalie per un retry_loop) o il tetto è genuinamente troppo basso per il task. Alza il tetto deliberatamente, non limitarti a fare retry.

​
4. firewall_approval_pending — è in attesa, non negata

firewall_approval_pending è l’unico 400 che non dovresti trattare come un block. Un verdetto pending_approval ha messo la chiamata a tool in attesa di un umano; il corpo dell’errore porta un id di approvazione. La chiamata non è fallita — sta aspettando.
  1. Un revisore la risolve — dalla console (Developer+) o tramite il tuo callback webhook HMAC (POST /api/v1/firewall/approvals/:id/callback).
  2. Il tuo agent fa polling su GET /api/v1/firewall/approvals/:id (token del gateway) sull’id dall’errore.
  3. Una volta approvata, ri-invia la chiamata originale con l’header monouso X-OrcaRouter-Firewall-Approval, e il gateway la lascia passare quella sola volta.
Vedi Firewall → Approvazione umana per il loop HITL completo.

​
5. Non è un block di sicurezza? Escludi prima la chiave

Non ogni 400 è un verdetto di guardrail o firewall. Prima di immergerti nei feed, escludi i vincoli della chiave — questi rifiutano prima che qualsiasi policy giri e non portano i codici di sicurezza qui sopra:
L’allow-list model_limits della chiave non include il modello richiesto. Le richieste per un modello fuori dalla lista vengono rifiutate in anticipo. Aggiungi il modello alla chiave o chiamane uno consentito.
La chiave ha un’allow-list allow_ips e la richiesta è arrivata da un indirizzo fuori da essa. Aggiungi l’IP / CIDR del chiamante o chiama da una rete consentita.
Il tetto credit_limit_usd della chiave è esaurito (0 significa illimitato). Alza il tetto o ruota verso una chiave con margine.
Gli hook del gateway (evaluate, dispatch MCP) richiedono una chiave con is_firewall_gateway=true. Una normale chiave di relay riceve 403. Conia una chiave con scope firewall-gateway per quelle rotte.

​
6. Il flusso di triage di due minuti

Block sul testo di prompt o risposta

Il codice è guardrail_blocked → apri Matches, filtra action=block, leggi Stage + Detail. Correggi il contenuto o la regola; provalo nella tab Test del guardrail.

Block su una chiamata a tool

Il codice è firewall_blocked → apri Events, filtra verdict=deny, leggi la superficie + motivazione. Correggi la chiamata o la regola; provalo nella tab Test del firewall.

La chiamata è in attesa

Il codice è firewall_approval_pending → fai polling sull’id di approvazione e ri-invia con l’header di approvazione. Niente da debuggare.

Nessuno dei precedenti

Nessun codice di sicurezza → controlla la chiave: model_limits, allow_ips, credit_limit_usd, o 403 per uno scope di gateway mancante.

​
7. Riferimenti correlati

Codici di errore

La tabella completa dei codici — ogni block, hold e rifiuto che il gateway può restituire.

Glossario dei verdetti

Cosa significa ogni verdetto del firewall e quando si risolve in un deny.

Glob e JSONPath

Decodifica il tool_name_glob e l’args_match che hanno corrisposto alla tua chiamata.

Guardrails vs Firewall

Quale piano è scattato — filtraggio del testo o governance delle azioni.
Per i controlli in sé, vedi Guardrails e Firewall; per le minacce che fermano, parti dal modello di threat.