Перейти к основному содержанию
Когда guardrail или firewall останавливает запрос, OrcaRouter возвращает типизированную ошибку, по которой ваш код может ветвиться, — а не расплывчатый 400. Три кода безопасности покрывают случаи, которые вы встретите: проверенный промпт или ответ, отклонённый вызов инструмента и вызов инструмента, удержанный для подтверждения человеком. Эта страница — справочник по этим кодам: use-case каждого, точный HTTP-статус, во что он вам обходится, и одно правило, которое важнее всего: логика повтора должна обрабатывать их как особый случай. Все три помечены skip-retry; слепой повторный прогон того же вызова просто снова срабатывает на том же контроле.
Это коды применения — шлюз решает не пересылать ваш вызов. Они отличаются от ошибок вышестоящего провайдера (429 модели, переполнение контекста) и от сбоев аутентификации. О том, почему конкретный запрос был остановлен, см. Почему это было заблокировано?.

​
1. Коды ошибок безопасности LLM с первого взгляда

Каждая блокировка безопасности возвращает HTTP 400 с телом ошибки в форме OpenAI (error.code — типизированная строка ниже). На нативных маршрутах Claude (/v1/messages) тот же код едет в форме ошибки Claude, так что SDK-маршрутизация детерминирована между протоколами.
КодОстанавливаетСтоимость квоты
guardrail_blockedПромпт или ответ, попавший под правило blockНет
firewall_blockedОтклонённый вызов инструмента / рекламуНет токенов модели
firewall_approval_pendingВызов инструмента, удержанный для ревьюера-человекаНет токенов модели
Ветвитесь по error.code, никогда по строке сообщения. Сообщения называют конкретный guardrail, правило или инструмент и будут меняться; коды — стабильный контракт.

​
2. guardrail_blocked — проверенный промпт или ответ

Возвращается, когда срабатывает правило guardrail с действием block — слово из denylist’а, совпадение по regex, сущность PII или секрет, который вы решили блокировать, а не маскировать, вердикт llm_judge или проваленная проверка grounding. HTTP 400. Сообщение называет guardrail и сработавшее правило.
Заблокированный запрос не стоит квоты. Блокировка на стадии входа срабатывает до учёта, так что ничего никогда не тарифицируется. Блокировка на стадии выхода выполняется после того, как модель ответила, поэтому шлюз возвращает предварительно списанную квоту перед возвратом ошибки. В любом случае вы ничего не платите за заблокированный вызов.
Вердикт — свойство содержимого, а не канала. Повторный прогон того же промпта — даже на другой модели — даёт ту же блокировку. Исправьте вход (или политику) вместо повтора.
Правила mask не возвращают этот код. Замаскированное совпадение (например, jane@acme.com → [EMAIL]) редактируется на месте, и вызов продолжается нормально — вы получаете 200, просто без чувствительного фрагмента. Только действие block выдаёт guardrail_blocked. (flag вообще ничего не меняет в трафике.)
{
  "error": {
    "type": "openai_error",
    "code": "guardrail_blocked",
    "message": "request blocked by guardrail \"pii-shield\": rule ssn (block)"
  }
}
О типах правил, стадиях и действиях за этим кодом см. Guardrails. О конверте ошибки поле за полем см. Полезные нагрузки вебхуков и ошибок.

​
3. firewall_blocked — отклонённый вызов инструмента

Возвращается, когда firewall разрешает вердикт deny для вызова инструмента — деструктивная shell-команда, fetch в форме SSRF, egress-назначение в deny-списке или навык в режиме block. Как именно проявляется отказ, зависит от поверхности применения:

inbound / response / egress

HTTP 400 с error.code = firewall_blocked. Тело несёт структурированные error.metadata (reason_code, факторы риска factors, risk_score), так что вы можете объяснить блокировку, а не просто увидеть её.

поверхность mcp

Возвращается как ошибка инструмента (firewall deny: <reason>), а не сбой транспорта — так что модель видит отказ и может выбрать другой инструмент, спросить пользователя или остановиться вместо падения прогона.
sanitize — это не блокировка. Вердикт sanitize редактирует совпавшие подстроки из аргументов вызова инструмента и пересылает очищенный вызов — он никогда не возвращает firewall_blocked. (Единственное исключение: на поверхности inbound, где ещё нет аргументов времени вызова, sanitize эскалирует до блокировки.)
{
  "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"]
    }
  }
}
По части квоты блокировка на inbound срабатывает до вызова вышестоящей модели, так что она стоит нуля токенов модели. См. Глоссарий вердиктов для каждого вердикта и Опасные вызовы инструментов для угроз, от которых защищает этот код.

​
4. firewall_approval_pending — удержано для человека

Возвращается в тот миг, когда вызов инструмента попадает под вердикт pending_approval. Шлюз human-in-the-loop не может быть блокирующим inline- ожиданием, так что шлюз возвращает ответ held немедленно, а не делает long-polling. HTTP 400. Ошибка несёт id подтверждения, так что ваш агент знает, какое удержание разрешать. Это единственный код, на который вы отвечаете разрешением и повторной отправкой, а не трактовкой его как терминального сбоя:
1

Прочитайте id подтверждения из held-ошибки

Id восстанавливается из тела ошибки. Не повторяйте вызов пока — наивный повтор просто снова удерживает.
2

Дождитесь решения

Ревьюер разрешает его из консоли (Developer+), или ваша система подтверждений получает подписанный HMAC вебхук-колбэк. Ваш агент опрашивает GET /api/v1/firewall/approvals/:id для состояния.
3

Отправьте повторно с токеном подтверждения

После одобрения повторно выпустите исходный вызов с одноразовым заголовком X-OrcaRouter-Firewall-Approval. Шлюз распознаёт id и пропускает этот один вызов.
Маршруты подтверждений (/api/v1/firewall/approvals/*) работают на ключе с областью firewall-gateway, а не на вашей консольной сессии. См. Подтверждение человеком (HITL) для полного цикла и Полезные нагрузки вебхуков для подписи колбэка.

​
5. Почему все три пропускают повтор

Стандартная SDK-логика повтора предполагает, что 400 может удаться со второй попытки. Эти коды ломают это предположение — блокировка детерминирована, так что слепой повтор тратит round trip и (для удержанных вызовов) молча ставит подтверждение в очередь заново.
Собственная внутренняя машинерия повтора/отката OrcaRouter никогда не переотправляет вызов, вернувший один из этих кодов, на другой канал. Отразите это в своём клиенте: на код безопасности остановитесь и действуйте по вердикту, не зацикливайтесь.
  • guardrail_blocked → исправьте вход или ослабьте политику; покажите отказ пользователю. Не повторяйте.
  • firewall_blocked → действие запрещено; пусть агент выберет другой инструмент или попросит помощи. Не повторяйте.
  • firewall_approval_pending → разрешите удержание, затем переотправьте один раз с заголовком подтверждения (§4). Повтор без заголовка удерживает заново.

​
6. Сводка по квоте и биллингу

Блокировка безопасности никогда не тарифицирует вам заблокированную единицу работы.
КодКогда срабатываетИтог по биллингу
guardrail_blocked (вход)До вызова моделиНикогда не учитывается
guardrail_blocked (выход)После того, как модель ответилаПредварительно списанная квота возвращается
firewall_blocked (inbound)До вызова моделиНет токенов модели
firewall_approval_pendingДо диспетчаНет токенов модели
Правило guardrail llm_judge или grounding действительно вызывает модель, чтобы прийти к вердикту, и эти токены судьи тарифицируются отдельной подстрокой судьи — даже когда вердикт — блокировка. Это стоимость проверки, а не самого заблокированного запроса.

​
7. Сопутствующие справочники

Почему это было заблокировано?

Проследите одну блокировку до точного правила, поверхности и причины, которые её произвели.

Глоссарий вердиктов

Каждый вердикт firewall — allow, audit, deny, sanitize, pending_approval, cap_cost — и что каждый выдаёт.

Полезные нагрузки вебхуков и ошибок

Полный конверт ошибки, поля error.metadata и подпись колбэка подтверждения.

Режимы применения

Shadow, observe и enforce — когда вердикт реально меняет трафик.
О контролях, которые производят эти коды, см. Guardrails и Firewall; о словаре см. Глоссарий концепций.