Przejdź do głównej treści
Gdy guardrail lub firewall zatrzyma żądanie, OrcaRouter zwraca typowany błąd, na który twój kod może się rozgałęzić — nie mgliste 400. Trzy kody bezpieczeństwa pokrywają przypadki, które zobaczysz: prześwietlony prompt lub odpowiedź, odrzucone wywołanie narzędzia oraz wywołanie narzędzia wstrzymane do zatwierdzenia przez człowieka. Ta strona to referencja tych kodów — przypadek użycia każdego, dokładny status HTTP, ile cię kosztuje oraz jedna reguła, która ma największe znaczenie: logika ponawiania musi traktować je w sposób szczególny. Wszystkie trzy są oznaczone jako skip-retry; ślepe ponowne uruchomienie tego samego wywołania po prostu znów uruchamia tę samą kontrolę.
To są kody egzekwowania — brama decydująca, by nie przekazać twojego wywołania. Różnią się od błędów dostawcy nadrzędnego (model 429, przepełnienie kontekstu) i od awarii uwierzytelnienia. Aby dowiedzieć się, dlaczego konkretne żądanie zostało zatrzymane, zobacz Dlaczego to zostało zablokowane?.

​
1. Kody błędów bezpieczeństwa llm w skrócie

Każda blokada bezpieczeństwa zwraca HTTP 400 z ciałem błędu w kształcie OpenAI (error.code to typowany łańcuch poniżej). Na natywnych trasach Claude (/v1/messages) ten sam kod podróżuje w kształcie błędu Claude, więc routing SDK jest deterministyczny w różnych protokołach.
KodZatrzymujeKoszt kwoty
guardrail_blockedPrompt lub odpowiedź, która trafiła w regułę blockBrak
firewall_blockedOdrzucone wywołanie narzędzia / ogłoszenieBrak tokenów modelu
firewall_approval_pendingWywołanie narzędzia wstrzymane dla recenzenta-człowiekaBrak tokenów modelu
Rozgałęziaj na error.code, nigdy na łańcuch komunikatu. Komunikaty nazywają konkretny guardrail, regułę lub narzędzie i będą się zmieniać; kody to stabilny kontrakt.

​
2. guardrail_blocked — prześwietlony prompt lub odpowiedź

Zwracany, gdy reguła guardrail z akcją block odpala — słowo kluczowe z listy zakazanej, trafienie regex, encja PII lub sekret, które zdecydowałeś się zablokować zamiast maskować, werdykt llm_judge lub nieudane sprawdzenie ugruntowania. HTTP 400. Komunikat nazywa guardrail i regułę, która odpaliła.
Zablokowane żądanie nie kosztuje kwoty. Blokada na etapie wejścia odpala przed metrowaniem, więc nic nigdy nie jest naliczane. Blokada na etapie wyjścia działa po odpowiedzi modelu, więc brama zwraca wstępnie skonsumowaną kwotę przed zwróceniem błędu. Tak czy inaczej nie płacisz nic za zablokowane wywołanie.
Werdykt jest właściwością treści, nie kanału. Ponowne uruchomienie tego samego promptu — nawet wobec innego modelu — produkuje tę samą blokadę. Napraw wejście (lub politykę) zamiast ponawiać.
Reguły mask nie zwracają tego kodu. Zamaskowane dopasowanie (np. jane@acme.com → [EMAIL]) jest redagowane w miejscu, a wywołanie przebiega normalnie — dostajesz 200, tylko z usuniętym wrażliwym fragmentem. Wyłącznie akcja block wystawia guardrail_blocked. (flag nie zmienia w ruchu niczego.)
{
  "error": {
    "type": "openai_error",
    "code": "guardrail_blocked",
    "message": "request blocked by guardrail \"pii-shield\": rule ssn (block)"
  }
}
Po typy reguł, etapy i akcje stojące za tym kodem zobacz Guardrails. Po kopertę błędu pole po polu zobacz Webhook i ładunki błędów.

​
3. firewall_blocked — odrzucone wywołanie narzędzia

Zwracany, gdy firewall rozwiązuje werdykt deny dla wywołania narzędzia — destrukcyjne polecenie shella, pobranie w kształcie SSRF, cel egress na liście zakazanej lub skill w trybie block. Jak odrzucenie się objawia, zależy od powierzchni egzekwowania:

inbound / response / egress

HTTP 400 z error.code = firewall_blocked. Ciało niesie ustrukturyzowane error.metadata (reason_code, czynniki ryzyka factors, risk_score), abyś mógł wyjaśnić blokadę, nie tylko ją zobaczyć.

powierzchnia mcp

Zwracany jako błąd narzędzia (firewall deny: <reason>), nie jako awaria transportu — więc model widzi odrzucenie i może wybrać inne narzędzie, zapytać użytkownika lub zatrzymać się, zamiast wysypać uruchomienie.
sanitize nie jest blokadą. Werdykt sanitize redaguje dopasowane podłańcuchy z argumentów wywołania narzędzia i przesyła oczyszczone wywołanie — nigdy nie zwraca firewall_blocked. (Jeden wyjątek: na powierzchni inbound, gdzie nie ma jeszcze argumentów czasu wywołania, sanitize eskaluje do odrzucenia.)
{
  "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"]
    }
  }
}
Od strony kwoty blokada inbound odpala przed wywołaniem modelu nadrzędnego, więc nie kosztuje żadnych tokenów modelu. Zobacz Słownik werdyktów po każdy werdykt oraz Niebezpieczne wywołania narzędzi po zagrożenia, przed którymi ten kod broni.

​
4. firewall_approval_pending — wstrzymane dla człowieka

Zwracany w chwili, gdy wywołanie narzędzia trafia w werdykt pending_approval. Bramka z człowiekiem w pętli nie może być blokującym oczekiwaniem inline, więc brama zwraca odpowiedź wstrzymane natychmiast, zamiast odpytywać długo. HTTP 400. Błąd niesie id zatwierdzenia, aby twój agent wiedział, które wstrzymanie rozstrzygnąć. To jest jeden kod, na który reagujesz przez rozstrzygnięcie i ponowne wysłanie — nie traktując go jako terminalnej awarii:
1

Odczytaj id zatwierdzenia ze wstrzymanego błędu

Id da się odzyskać z ciała błędu. Nie ponawiaj jeszcze wywołania — naiwne ponowienie po prostu znów je wstrzyma.
2

Czekaj na decyzję

Recenzent rozstrzyga je z konsoli (Developer+) lub twój system zatwierdzeń dostaje podpisany HMAC webhook callback. Twój agent odpytuje GET /api/v1/firewall/approvals/:id o stan.
3

Wyślij ponownie z tokenem zatwierdzenia

Po zatwierdzeniu ponownie wystaw oryginalne wywołanie z jednorazowym nagłówkiem X-OrcaRouter-Firewall-Approval. Brama rozpoznaje id i przepuszcza to jedno wywołanie.
Trasy zatwierdzeń (/api/v1/firewall/approvals/*) działają na kluczu w zakresie firewall-gateway, nie na sesji konsoli. Zobacz Zatwierdzenie przez człowieka (HITL) po pełną pętlę oraz Ładunki webhooka po sygnaturę callbacku.

​
5. Dlaczego wszystkie trzy pomijają ponawianie

Standardowa logika ponawiania SDK zakłada, że 400 może się powieść przy drugiej próbie. Te kody łamią to założenie — blokada jest deterministyczna, więc ślepe ponowienie marnuje rundę, a (dla wstrzymanych wywołań) po cichu ponownie kolejkuje zatwierdzenie.
Własna wewnętrzna maszyneria ponawiania/fallbacku OrcaRouter nigdy nie próbuje ponownie wywołania, które zwraca jeden z tych kodów, wobec innego kanału. Odzwierciedl to w swoim kliencie: na kodzie bezpieczeństwa zatrzymaj się i zadziałaj wedle werdyktu, nie zapętlaj.
  • guardrail_blocked → napraw wejście lub rozluźnij politykę; wystaw odmowę użytkownikowi. Nie ponawiaj.
  • firewall_blocked → akcja jest niedozwolona; niech agent wybierze inne narzędzie lub poprosi o pomoc. Nie ponawiaj.
  • firewall_approval_pending → rozstrzygnij wstrzymanie, a potem wyślij ponownie raz z nagłówkiem zatwierdzenia (§4). Ponowienie bez nagłówka znów wstrzymuje.

​
6. Podsumowanie kwoty i rozliczeń

Blokada bezpieczeństwa nigdy nie nalicza ci za zablokowaną jednostkę pracy.
KodKiedy odpalaSkutek rozliczeniowy
guardrail_blocked (input)Przed wywołaniem modeluNigdy nie metrowane
guardrail_blocked (output)Po odpowiedzi modeluWstępnie skonsumowana kwota zwrócona
firewall_blocked (inbound)Przed wywołaniem modeluBrak tokenów modelu
firewall_approval_pendingPrzed dyspozycjąBrak tokenów modelu
Reguła llm_judge lub grounding guardraila faktycznie wywołuje model, aby dojść do werdyktu, a te tokeny sędziego są rozliczane jako osobna podlinia sędziego — nawet gdy werdyktem jest blokada. To koszt sprawdzenia, nie samego zablokowanego żądania.

​
7. Powiązane referencje

Dlaczego to zostało zablokowane?

Prześledź pojedynczą blokadę do dokładnej reguły, powierzchni i powodu, które ją wyprodukowały.

Słownik werdyktów

Każdy werdykt firewalla — allow, audit, deny, sanitize, pending_approval, cap_cost — i co każdy emituje.

Webhook i ładunki błędów

Pełna koperta błędu, pola error.metadata oraz sygnatura callbacku zatwierdzenia.

Tryby egzekwowania

Shadow, observe i enforce — kiedy werdykt faktycznie zmienia ruch.
Po kontrole, które produkują te kody, zobacz Guardrails i Firewall; po słownictwo zobacz Słownik pojęć.