Chuyển đến nội dung chính
Khi một guardrail hoặc firewall chặn một request, OrcaRouter trả về một lỗi có kiểu mà code của bạn có thể rẽ nhánh dựa vào — không phải một 400 mơ hồ. Ba mã bảo mật bao quát các tình huống bạn sẽ gặp: một prompt hoặc phản hồi bị sàng lọc, một cuộc gọi tool bị từ chối, và một cuộc gọi tool được giữ lại chờ con người phê duyệt. Trang này là tham chiếu cho các mã đó — use-case của từng cái, trạng thái HTTP chính xác, nó tốn kém gì của bạn, và một quy tắc quan trọng nhất: logic retry phải xử lý đặc biệt cho chúng. Cả ba đều được đánh dấu skip-retry; chạy lại mù quáng cùng một cuộc gọi chỉ kích hoạt lại đúng cùng một kiểm soát đó.
Đây là các mã thực thi — gateway quyết định không chuyển tiếp cuộc gọi của bạn. Chúng khác với các lỗi từ provider upstream (một model 429, một context overflow) và khác với các lỗi xác thực. Để biết tại sao một request cụ thể bị chặn, xem Tại sao bị chặn?.

​
1. Các mã lỗi bảo mật llm trong nháy mắt

Mọi lần chặn bảo mật đều trả về HTTP 400 với một error body kiểu OpenAI (error.code là chuỗi có kiểu bên dưới). Trên các route Claude native (/v1/messages), cùng mã đó đi trong error shape của Claude, nên việc định tuyến SDK là xác định được trên các protocol.
MãChặnChi phí quota
guardrail_blockedMột prompt hoặc phản hồi trúng quy tắc blockKhông
firewall_blockedMột cuộc gọi tool / quảng bá bị từ chốiKhông tốn model token
firewall_approval_pendingMột cuộc gọi tool được giữ chờ người duyệtKhông tốn model token
Rẽ nhánh theo error.code, không bao giờ theo chuỗi message. Message nêu tên guardrail, quy tắc, hoặc tool cụ thể và sẽ thay đổi; các mã là một hợp đồng ổn định.

​
2. guardrail_blocked — một prompt hoặc phản hồi bị sàng lọc

Trả về khi một quy tắc guardrail với hành động block kích hoạt — một từ khóa trong denylist, một regex trúng, một thực thể PII hoặc secret mà bạn chọn block thay vì mask, một verdict llm_judge, hoặc một kiểm tra grounding thất bại. HTTP 400. Message nêu tên guardrail và quy tắc đã kích hoạt.
Một request bị chặn không tốn quota. Một lần chặn ở giai đoạn input kích hoạt trước khi đo lường, nên không bao giờ có gì bị tính phí. Một lần chặn ở giai đoạn output chạy sau khi model phản hồi, nên gateway hoàn lại quota đã tiêu trước khi trả về lỗi. Dù theo cách nào bạn cũng không trả gì cho một cuộc gọi bị chặn.
Verdict là một thuộc tính của nội dung, không phải của kênh. Chạy lại cùng một prompt — kể cả với một model khác — cũng tạo ra cùng một lần chặn. Hãy sửa input (hoặc chính sách) thay vì retry.
Các quy tắc mask không trả về mã này. Một match được mask (vd: jane@acme.com → [EMAIL]) bị redact tại chỗ và cuộc gọi tiến hành bình thường — bạn nhận được 200, chỉ là đoạn nhạy cảm đã bị loại bỏ. Chỉ hành động block mới làm nổi lên guardrail_blocked. (flag không thay đổi gì về traffic cả.)
{
  "error": {
    "type": "openai_error",
    "code": "guardrail_blocked",
    "message": "request blocked by guardrail \"pii-shield\": rule ssn (block)"
  }
}
Về các kiểu quy tắc, giai đoạn, và hành động đằng sau mã này, xem Guardrails. Về error envelope theo từng trường, xem Webhook & payload lỗi.

​
3. firewall_blocked — một cuộc gọi tool bị từ chối

Trả về khi firewall phân giải ra một verdict deny cho một cuộc gọi tool — một lệnh shell phá hủy, một fetch dạng SSRF, một đích đến egress nằm trong deny list, hoặc một skill ở chế độ block. Cách một lần deny lộ ra phụ thuộc vào bề mặt thực thi:

inbound / response / egress

HTTP 400 với error.code = firewall_blocked. Body mang theo error.metadata có cấu trúc (reason_code, các factors rủi ro, risk_score) để bạn có thể giải thích lần chặn, không chỉ thấy nó.

bề mặt mcp

Trả về như một lỗi tool (firewall deny: <reason>), không phải một lỗi transport — nên model thấy việc bị từ chối và có thể chọn một tool khác, hỏi người dùng, hoặc dừng lại, thay vì làm sập lần chạy.
sanitize không phải là một lần block. Một verdict sanitize redact các chuỗi con đã khớp khỏi các argument của cuộc gọi tool và chuyển tiếp cuộc gọi đã được làm sạch — nó không bao giờ trả về firewall_blocked. (Ngoại lệ duy nhất: trên bề mặt inbound, nơi chưa có argument lúc gọi, sanitize leo thang thành deny.)
{
  "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"]
    }
  }
}
Về mặt quota, một lần chặn inbound kích hoạt trước cuộc gọi model upstream, nên nó tốn không model token. Xem Bảng thuật ngữ verdict để biết mọi verdict, và Cuộc gọi tool nguy hiểm để biết các mối đe dọa mà mã này phòng vệ.

​
4. firewall_approval_pending — giữ lại chờ con người

Trả về ngay khoảnh khắc một cuộc gọi tool trúng một verdict pending_approval. Một cổng human-in-the-loop không thể là một lần chờ inline gây block, nên gateway trả về một phản hồi đã giữ ngay lập tức thay vì long-poll. HTTP 400. Lỗi mang theo approval id để agent của bạn biết phải giải quyết lần giữ nào. Đây là mã duy nhất bạn phản hồi bằng cách giải quyết và gửi lại — chứ không phải xử lý nó như một thất bại cuối cùng:
1

Đọc approval id từ lỗi đã giữ

Id có thể lấy ra từ error body. Đừng retry cuộc gọi ngay — một lần retry ngây thơ chỉ giữ lại lần nữa.
2

Chờ một quyết định

Một người duyệt giải quyết nó từ console (Developer+), hoặc hệ thống phê duyệt của bạn nhận được một webhook callback ký HMAC. Agent của bạn poll GET /api/v1/firewall/approvals/:id để lấy trạng thái.
3

Gửi lại với approval token

Một khi được phê duyệt, phát lại cuộc gọi gốc mang theo header dùng một lần X-OrcaRouter-Firewall-Approval. Gateway nhận ra id và cho đúng cuộc gọi đó đi qua.
Các route phê duyệt (/api/v1/firewall/approvals/*) chạy trên một key firewall-gateway-scoped, không phải phiên console của bạn. Xem Phê duyệt của con người (HITL) để biết vòng lặp đầy đủ và Payload webhook để biết chữ ký callback.

​
5. Tại sao cả ba đều bỏ qua retry

Logic retry SDK tiêu chuẩn giả định một 400 có thể thành công ở lần thử thứ hai. Các mã này phá vỡ giả định đó — lần chặn là xác định, nên một lần retry mù quáng lãng phí một round trip và (với các cuộc gọi đã giữ) âm thầm xếp hàng lại một lần phê duyệt.
Cỗ máy retry/fallback nội bộ của chính OrcaRouter không bao giờ thử lại một cuộc gọi trả về một trong các mã này trên một kênh khác. Hãy phản chiếu điều đó trong client của bạn: với một mã bảo mật, dừng lại và hành động theo verdict, đừng lặp.
  • guardrail_blocked → sửa input hoặc nới chính sách; làm nổi lên việc từ chối cho người dùng. Đừng retry.
  • firewall_blocked → hành động không được phép; hãy cho agent chọn một tool khác hoặc yêu cầu trợ giúp. Đừng retry.
  • firewall_approval_pending → giải quyết lần giữ, rồi gửi lại một lần với header phê duyệt (§4). Một lần retry không có header sẽ giữ lại.

​
6. Tóm tắt quota & billing

Một lần chặn bảo mật không bao giờ tính phí bạn cho đơn vị công việc bị chặn.
MãKhi nào kích hoạtKết quả billing
guardrail_blocked (input)Trước cuộc gọi modelKhông bao giờ đo lường
guardrail_blocked (output)Sau khi model phản hồiQuota tiêu trước được hoàn
firewall_blocked (inbound)Trước cuộc gọi modelKhông tốn model token
firewall_approval_pendingTrước khi dispatchKhông tốn model token
Một quy tắc llm_judge hoặc grounding của guardrail thực sự gọi một model để đi tới verdict của nó, và các judge token đó được tính như một dòng phụ judge riêng — kể cả khi verdict là một lần block. Đó là chi phí của việc kiểm tra, không phải của chính request bị chặn.

​
7. Tham chiếu liên quan

Tại sao bị chặn?

Truy vết một lần chặn đơn lẻ về đúng quy tắc, bề mặt, và lý do đã tạo ra nó.

Bảng thuật ngữ verdict

Mọi verdict của firewall — allow, audit, deny, sanitize, pending_approval, cap_cost — và mỗi cái phát ra gì.

Webhook & payload lỗi

Error envelope đầy đủ, các trường error.metadata, và chữ ký callback phê duyệt.

Chế độ thực thi

Shadow, observe, và enforce — khi nào một verdict thực sự thay đổi traffic.
Về các kiểm soát tạo ra các mã này, xem Guardrails và Firewall; về từ vựng, xem Bảng thuật ngữ khái niệm.