Chuyển đến nội dung chính
Khi một guardrail từ chối một cuộc gọi, gateway trả lời ứng dụng của bạn với HTTP 400 và mã lỗi guardrail_blocked. Trang này là tài liệu tham khảo đích cho một lỗi đó: body trông như thế nào, tại sao nó hành xử theo cách của nó, và cách xử lý nó trong code client. Về engine chính sách đằng sau nó, xem Tổng quan Guardrails và tài liệu tham khảo đầy đủ.

​
1. Khi nào bạn thấy guardrail_blocked

Một guardrail là một danh sách quy tắc có thứ tự mà gateway chạy đối với input request và output mô hình. Khi một quy tắc có hành động là block kích hoạt, cuộc gọi bị từ chối — mô hình thượng nguồn không bao giờ được gọi (giai đoạn input) hoặc câu trả lời của nó bị giữ lại (giai đoạn output). Client nhận một 400 mang guardrail_blocked. Không hành động nào khác tạo ra lỗi này. mask redact match và cho văn bản đã làm sạch đi qua, flag ghi lại một match mà không thay đổi traffic, và các hành động định hình prompt (annotate, spotlight) cho cuộc gọi tiếp tục trong khi thêm một ghi chú hoặc bọc văn bản không đáng tin cậy. Trong năm hành động, chỉ block từ chối. Xem Hành động.
guardrail_blocked là một từ chối nội dung (text vào, text ra). Từ chối chính sách tool đồng hành là firewall_blocked từ Agent Firewall — một lỗi khác với hình dạng khác. Xem guardrails so với firewall.

​
2. Response body

Block được trả về trong envelope lỗi định dạng OpenAI tiêu chuẩn của gateway. Trên một endpoint kiểu OpenAI (/v1/chat/completions, /v1/responses): 
{
  "error": {
    "message": "request blocked by guardrail \"pii-shield\": pii(ssn)",
    "type": "orcarouter_api_error",
    "param": "",
    "code": "guardrail_blocked"
  }
}
Các trường bạn dựa vào:
Định danh máy ổn định. Phân nhánh trên cái này, không phải trên chuỗi message. Nó là cùng giá trị trên mọi endpoint và không bao giờ được bản địa hóa.
Có thể đọc được bởi con người. Dạng là request blocked by guardrail "<name>": <detail>, trong đó <detail> tóm tắt loại quy tắc đã kích hoạt dưới dạng <type>(<rule-detail>) — ví dụ pii(pii: ssn) hoặc keyword(matched 1 keyword(s)). Một block giai đoạn output đọc response blocked by guardrail "<name>": <detail>, nên động từ cho bạn biết giai đoạn nào đã từ chối cuộc gọi. Message được đưa qua masking thông tin nhạy cảm trước khi rời gateway, nên đừng kỳ vọng chuỗi con đã match thô ở đây.
Loại lỗi gateway chung trên các endpoint kiểu OpenAI. Tín hiệu phân biệt là code, không phải type.
Trên bề mặt Anthropic native (/v1/messages), envelope có định dạng Claude — {"error": {"type": ..., "message": ...}} — và guardrail_blocked hiện ra trong trường type, nên một Claude SDK native có thể phân biệt một từ chối chính sách với một thất bại gateway chung.
Muốn verdict chính xác trước khi bạn phát hành một quy tắc? Tab Test trong console đánh giá chính sách hiện tại trên văn bản mẫu mà không có cuộc gọi thượng nguồn và không có quota — xem testing & eval.

​
3. Tại sao guardrail_blocked không tốn quota

Một request bị block là miễn phí — nó không bao giờ trừ số dư tín dụng của bạn.
Giai đoạnKhi nào block kích hoạtHiệu ứng quota
inputTrước cuộc gọi thượng nguồn, trước khi đo lườngKhông có gì được đo
outputSau khi mô hình trả lời, trước khi câu trả lời trả vềQuota đã tiêu trước được hoàn lại
Nên một block input không bị tính gì vì việc đo lường chưa xảy ra, và một block output đảo ngược khoản giữ mà gateway đã đặt trước khi chuyển tiếp. Dù cách nào, người gọi trả cho block bằng một 400, không phải bằng tín dụng. Xem giai đoạn input và giai đoạn output.

​
4. Tại sao guardrail_blocked bỏ qua retry

Lỗi được gắn thẻ skip-retry. Định tuyến của riêng gateway sẽ không chuyển request này sang một channel khác, vì block là thuộc tính của nội dung và chính sách của bạn — chạy lại prompt giống hệt sẽ chỉ block lại trên channel kế tiếp và phí lần thử.
Đừng đặt guardrail_blocked trong vòng lặp retry của client bạn nữa. Nó tất định: cùng prompt đối với cùng chính sách block mỗi lần. Retry đốt độ trễ cho một kết quả không thể thay đổi. Hãy coi nó như một từ chối cuối cùng — sửa input, hoặc sửa chính sách.

​
5. Xử lý nó trong code client

Phân nhánh trên trường code và hiển thị một thông điệp hữu ích cho người dùng cuối thay vì retry. 
import httpx

resp = httpx.post(
    "https://api.orcarouter.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-orca-..."},
    json={
        "model": "openai/gpt-4o-mini",
        "messages": [{"role": "user", "content": "My SSN is 123-45-6789"}],
    },
)

if resp.status_code == 400:
    err = resp.json().get("error", {})
    if err.get("code") == "guardrail_blocked":
        # Terminal — do not retry. Tell the user what to change.
        raise ValueError(f"Blocked by policy: {err['message']}")

resp.raise_for_status()
Key sk-orca-... ở đây là một key relay — nó chỉ mang traffic /v1/*. Bạn không bao giờ chỉnh sửa một guardrail bằng nó; soạn và gắn chính sách là một hành động console / management-API trên phiên của bạn, và tạo hoặc chỉnh sửa một guardrail yêu cầu vai trò Developer+.

​
6. Xác nhận và tinh chỉnh một block

Mỗi quy tắc kích hoạt — bao gồm block — đều đáp xuống feed Matches của workspace với loại, hành động, giai đoạn, và một chuỗi chi tiết của nó. Đó là nơi bạn xác nhận quy tắc nào đã từ chối một cuộc gọi nhất định và phân loại dương tính giả.

Matches feed

Xem mọi block, mask, và flag với loại, hành động, và giai đoạn. Chuỗi con đã match chỉ xuất hiện khi Log raw content được bật.

Logging & quyền riêng tư

Raw content mặc định tắt — lập trường bảo thủ về quyền riêng tư. Bật nó cho từng guardrail khi bạn cần chuỗi con để phân loại.

Tinh chỉnh dương tính giả

Một dương tính giả là một tín hiệu tinh chỉnh, không phải lý do để tắt quy tắc. Đánh dấu nó và thu hẹp pattern.

Versioning

Đã thay đổi chính sách và muốn hoàn tác? Diff bất kỳ hai phiên bản nào và revert thành một phiên bản mới — lịch sử không bao giờ bị thay đổi.
Trên một phản hồi streaming, một block output vẫn áp dụng: scanner cắt stream giữa chừng trước khi bất kỳ nội dung bị block nào đến được client. mask output cũng áp dụng trong luồng trên stream — scanner viết lại match trong buffer cuộn trước khi tiền tố an toàn được phát. Xem phạm vi streaming và quy tắc an toàn-stream.

​
7. Liên quan