Chuyển đến nội dung chính
Một request trả về HTTP 400 và agent của bạn đứng khựng lại. Trước khi bạn đổi bất kỳ dòng code nào, gateway đã nói cho bạn biết chuyện gì xảy ra: mã lỗi nêu kiểm soát nào đã kích hoạt, và một trong hai feed nêu đúng quy tắc. Trang này là luồng tra-cứu-và-truy-vết — đọc mã, mở đúng feed, tìm ra quy tắc. Nếu bạn chỉ nhớ một điều: một 400 từ một kiểm soát bảo mật không phải là một bug trong prompt của bạn. Đó là một chính sách đang làm việc của nó. Việc của bạn là tìm ra chính sách nào, rồi quyết định sửa cuộc gọi hay nới quy tắc.

​
1. Tại sao request llm của tôi bị chặn? — bắt đầu với mã lỗi

Mọi lần chặn bảo mật trên gateway được host đều trả về HTTP 400 với một code máy đọc được trong error body kiểu OpenAI. Mã đó là ngã rẽ đầu tiên trên con đường — nó cho bạn biết phải gỡ lỗi mặt phẳng kiểm soát nào và mở feed nào. 
{
  "error": {
    "message": "tool \"shell.exec\" blocked by firewall: destructive shell command",
    "code": "firewall_blocked",
    "type": "invalid_request_error"
  }
}

guardrail_blocked

Một quy tắc nội dung Guardrail đã kích hoạt trên input request hoặc output của model. Truy vết nó trong feed Matches. Xem §2.

firewall_blocked

Một quy tắc Firewall đã từ chối một cuộc gọi tool. Truy vết nó trong feed Events. Xem §3.

firewall_approval_pending

Một cuộc gọi tool được giữ chờ con người phê duyệt — không bị từ chối. Hãy giải quyết nó, đừng gỡ lỗi. Xem §4.
Cả ba mã đều là skip-retry: chạy lại đúng cùng một cuộc gọi sẽ định tuyến tới cùng một chính sách và chặn lại. Retry là latency lãng phí — hãy sửa input hoặc quy tắc thay vào đó. Bảng mã đầy đủ nằm ở Mã lỗi.

​
2. guardrail_blocked — tìm quy tắc trong Matches

guardrail_blocked nghĩa là một chính sách nội dung gắn với key của bạn (hoặc mặc định của workspace) đã chạy một hành động block đối với input request hoặc output của model. Message chặn nêu tên guardrail và quy tắc, và request đó không tốn quota của bạn — chặn input kích hoạt trước khi đo lường; chặn output hoàn lại quota đã tiêu trước. Truy vết nó:
1

Mở feed Matches

Trong console, vào tab Matches trên trang Guardrails (GET /api/guardrail/match, Member). Mọi quy tắc kích hoạt đều rơi vào đây — RuleType, Action, Stage của nó, và một chuỗi Detail như pii: email, phone hoặc matched 3 keyword(s).
2

Lọc theo lần block

Lọc theo action = block và thời điểm của request. Hàng khớp cho bạn biết kiểu quy tắc (pii, regex, keyword, max_chars, llm_judge, grounding, external) và liệu nó kích hoạt ở giai đoạn input hay output.
3

Xem nó thực sự đã khớp gì

Mặc định feed ghi lại rằng một quy tắc đã kích hoạt và meta-string Detail của nó — không phải chuỗi con đã khớp. Bật Log raw content trên guardrail đó (mặc định tắt, tư thế bảo thủ về quyền riêng tư) để bắt được chuỗi vi phạm phục vụ phân loại. Công tắc này không có hiệu lực hồi tố.
Một lần chặn mà bạn tin là sai? Mở match và đánh dấu nó là false positive (POST /api/guardrail/match/:id/mark-fp, Admin). Để chứng minh bản sửa trước khi phát hành nó, hãy sửa quy tắc và chạy lại mẫu trong tab Test của trình soạn guardrail — không có cuộc gọi upstream, không tốn quota.

​
Một ví dụ cụ thể

Bạn gửi một câu trả lời hỗ trợ có chứa SSN của khách hàng. Guardrail pii-shield của bạn có một override entity_actions block trên ssn: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "ssn"],
  "entity_actions": { "ssn": "block" }
}
Gateway trả về 400 guardrail_blocked. Feed Matches hiển thị RuleType: pii, Action: block, Stage: input, Detail: pii: ssn. Cách sửa là một quyết định sản phẩm, không phải thay đổi code: nới override về mask (model không bao giờ thấy SSN, cuộc gọi đi qua), hoặc giữ lần block và loại bỏ SSN ở upstream. Xem Guardrails để biết tham chiếu đầy đủ về kiểu quy tắc và thực thể PII.

​
3. firewall_blocked — tìm verdict trong Events

firewall_blocked nghĩa là một chính sách Firewall đã từ chối một cuộc gọi tool. Trên bề mặt inbound nó lộ ra dưới dạng 400; qua MCP gateway nó lộ ra dưới dạng một lỗi tool (firewall deny: <reason>) để model có thể phản ứng thay vì sập. metadata của lỗi mang theo mã lý do, các factor rủi ro, và điểm số. Truy vết nó trong feed Events (GET /api/workspace/firewall/events, Developer+) — bản ghi thô đằng sau mọi lần đánh giá. Mỗi event mang theo một verdict và bề mặt mà nó được thấy:
VerdictNó nghĩa gì cho lần chặn của bạn
denyMột quy tắc (hoặc default_verdict) đã chặn cuộc gọi. Đây là firewall_blocked của bạn.
auditĐược phép nhưng ghi log — bao gồm một [shadow] “would deny” nếu chính sách ở chế độ shadow.
cap_costMức chi tiêu tích lũy của lần chạy vượt một cap theo từng quy tắc (cents); phân giải thành deny.
1

Lọc Events tới lần từ chối

Lọc theo verdict=deny, rồi theo tool, run_id, hoặc session_id để cô lập đúng cuộc gọi. Event nêu tên quy tắc đã khớp và bề mặt — inbound, response, mcp, hoặc egress.
2

Đọc lý do trên quy tắc đã khớp

Chuỗi lý do (vd: destructive shell command, egress host not allowed) cho bạn biết liệu quy tắc khớp trên tên tool, một mệnh đề args_match, hay một đích đến egress. Bảng thuật ngữ verdict và tham chiếu glob & JSONPath giải mã việc khớp.
3

Xác nhận với sandbox Test

Phát lại đúng cuộc gọi tool đó trong tab Test của Firewall (POST /api/workspace/firewall/test, Developer+) để thấy verdict, quy tắc đã khớp, và lý do — không dispatch gì, không ghi log gì.
Một lần deny cap_cost không phải là một quy tắc kích hoạt nhầm — lần chạy agent của bạn đã chạm trần chi tiêu mà bạn đặt. Hoặc lần chạy đang lặp (kiểm tra rollup Runs và feed bất thường để tìm một retry_loop) hoặc cap thực sự quá thấp cho tác vụ. Hãy nâng cap một cách có chủ đích, đừng chỉ retry.

​
4. firewall_approval_pending — nó được giữ, không bị từ chối

firewall_approval_pending là 400 duy nhất bạn không nên xử lý như một lần chặn. Một verdict pending_approval đã giữ cuộc gọi tool lại chờ con người; error body mang theo một approval id. Cuộc gọi chưa thất bại — nó đang chờ.
  1. Một người duyệt giải quyết nó — từ console (Developer+) hoặc qua HMAC webhook callback của riêng bạn (POST /api/v1/firewall/approvals/:id/callback).
  2. Agent của bạn poll GET /api/v1/firewall/approvals/:id (gateway token) trên id từ lỗi.
  3. Một khi được phê duyệt, gửi lại cuộc gọi gốc với header dùng một lần X-OrcaRouter-Firewall-Approval, và gateway cho nó đi qua đúng lần đó.
Xem Firewall → Phê duyệt của con người để biết vòng lặp HITL đầy đủ.

​
5. Không phải lần chặn bảo mật? Loại trừ key trước đã

Không phải mọi 400 đều là một verdict guardrail hay firewall. Trước khi bạn lao vào đào feed, hãy loại trừ các ràng buộc của key — những thứ này từ chối trước khi bất kỳ chính sách nào chạy và không mang các mã bảo mật ở trên:
Allow-list model_limits của key không bao gồm model được yêu cầu. Request cho một model ngoài danh sách bị từ chối ngay từ đầu. Thêm model vào key hoặc gọi một model được phép.
Key có một allow-list allow_ips và request đến từ một địa chỉ ngoài danh sách đó. Thêm IP / CIDR của bên gọi hoặc gọi từ một mạng được phép.
Trần credit_limit_usd của key đã cạn (0 nghĩa là không giới hạn). Nâng cap hoặc xoay sang một key còn dư địa.
Các hook gateway (evaluate, MCP dispatch) yêu cầu một key có is_firewall_gateway=true. Một relay key thường nhận 403. Hãy đúc một key firewall-gateway-scoped cho các route đó.

​
6. Luồng phân loại hai phút

Chặn trên văn bản prompt hoặc phản hồi

Mã là guardrail_blocked → mở Matches, lọc action=block, đọc Stage
  • Detail. Sửa nội dung hoặc quy tắc; chứng minh nó ở tab Test của guardrail.

Chặn trên một cuộc gọi tool

Mã là firewall_blocked → mở Events, lọc verdict=deny, đọc bề mặt + lý do. Sửa cuộc gọi hoặc quy tắc; chứng minh nó ở tab Test của firewall.

Cuộc gọi được giữ lại

Mã là firewall_approval_pending → poll approval id và gửi lại với header phê duyệt. Không có gì để gỡ lỗi.

Không phải các trường hợp trên

Không có mã bảo mật → kiểm tra key: model_limits, allow_ips, credit_limit_usd, hoặc 403 cho một gateway scope còn thiếu.

​
7. Tham chiếu liên quan

Mã lỗi

Bảng mã đầy đủ — mọi lần chặn, giữ, và từ chối mà gateway có thể trả về.

Bảng thuật ngữ verdict

Mỗi verdict của firewall nghĩa là gì và khi nào nó phân giải thành một deny.

Glob & JSONPath

Giải mã tool_name_glob và args_match đã khớp cuộc gọi của bạn.

Guardrails vs Firewall

Mặt phẳng nào đã kích hoạt — sàng lọc văn bản hay quản trị hành động.
Về chính các kiểm soát, xem Guardrails và Firewall; về các mối đe dọa chúng chặn, bắt đầu ở mô hình đe dọa.