메인 콘텐츠로 건너뛰기
guardrail이 호출을 거부하면, 게이트웨이는 당신의 애플리케이션에 HTTP 400과 오류 코드 guardrail_blocked로 응답합니다. 이 페이지는 그 하나의 오류에 대한 랜딩 레퍼런스입니다: 본문이 어떻게 보이는지, 왜 그런 방식으로 동작하는지, 그리고 클라이언트 코드에서 어떻게 처리하는지. 그 뒤의 정책 엔진은 Guardrails 개요와 전체 레퍼런스를 참조하세요.

​
1. guardrail_blocked를 볼 때

guardrail은 게이트웨이가 요청 입력과 모델 출력에 대해 실행하는 순서가 있는 규칙 목록입니다. 액션이 block인 규칙이 발동하면, 호출은 거부됩니다 — 업스트림 모델이 결코 호출되지 않거나(입력 스테이지) 그 답변이 보류됩니다(출력 스테이지). 클라이언트는 guardrail_blocked를 운반하는 400을 받습니다. 다른 어떤 액션도 이 오류를 발생시키지 않습니다. mask는 매치를 마스킹하고 정화된 텍스트를 통과시키고, flag는 트래픽을 변경하지 않고 매치를 기록하며, 프롬프트 형성 액션(annotate, spotlight)은 메모를 추가하거나 신뢰할 수 없는 텍스트를 감싸면서 호출을 진행시킵니다. 다섯 가지 액션 중 block만 거부합니다. 액션을 참조하세요.
guardrail_blocked는 콘텐츠 거부입니다(텍스트 입력, 텍스트 출력). 동반자인 툴 정책 거부는 Agent Firewall의 firewall_blocked입니다 — 다른 형태를 가진 다른 오류입니다. guardrails vs. firewall을 참조하세요.

​
2. 응답 본문

차단은 게이트웨이의 표준 OpenAI 형태 오류 봉투로 반환됩니다. OpenAI 스타일 엔드포인트(/v1/chat/completions, /v1/responses)에서: 
{
  "error": {
    "message": "request blocked by guardrail \"pii-shield\": pii(ssn)",
    "type": "orcarouter_api_error",
    "param": "",
    "code": "guardrail_blocked"
  }
}
당신이 키로 삼는 필드:
안정적인 기계 식별자. 메시지 문자열이 아니라 이것으로 분기하세요. 모든 엔드포인트에서 동일한 값이며 결코 현지화되지 않습니다.
사람이 읽을 수 있음. 형식은 request blocked by guardrail "<name>": <detail>이며, 여기서 <detail>은 발동한 규칙 타입을 <type>(<rule-detail>)로 요약합니다 — 예: pii(pii: ssn) 또는 keyword(matched 1 keyword(s)). 출력 스테이지 차단은 response blocked by guardrail "<name>": <detail>로 읽히므로, 동사가 어느 스테이지가 호출을 거부했는지 알려줍니다. 메시지는 게이트웨이를 떠나기 전에 민감 정보 마스킹을 거치므로, 여기서 원시 매치된 부분 문자열을 기대하지 마세요.
OpenAI 스타일 엔드포인트의 일반 게이트웨이 오류 타입. 구별 신호는 type이 아니라 code입니다.
네이티브 Anthropic 표면(/v1/messages)에서 봉투는 Claude 형태입니다 — {"error": {"type": ..., "message": ...}} — 그리고 guardrail_blocked는 type 필드에 나타나므로, 네이티브 Claude SDK는 정책 거부를 일반 게이트웨이 실패와 구별할 수 있습니다.
규칙을 출시하기 전에 정확한 판정을 원하나요? 콘솔 Test 탭은 업스트림 호출 없이, 쿼터 없이 샘플 텍스트에 대해 현재 정책을 평가합니다 — 테스트 및 평가를 참조하세요.

​
3. guardrail_blocked가 쿼터를 소모하지 않는 이유

차단된 요청은 무료입니다 — 당신의 크레딧 잔액에서 결코 차감하지 않습니다.
스테이지차단이 발동하는 시점쿼터 효과
input업스트림 호출 전, 계량에 앞서아무것도 계량되지 않음
output모델이 응답한 후, 답변이 반환되기 전사전 소모된 쿼터가 환불됨
따라서 입력 차단은 계량이 아직 일어나지 않았으므로 아무것도 청구되지 않고, 출력 차단은 게이트웨이가 전달 전에 둔 홀드를 되돌립니다. 어느 쪽이든 호출자는 차단에 대해 크레딧이 아니라 400으로 지불합니다. 입력 스테이지와 출력 스테이지를 참조하세요.

​
4. guardrail_blocked가 재시도를 건너뛰는 이유

오류는 skip-retry로 태그됩니다. 게이트웨이 자체 라우팅은 이 요청을 다른 채널로 페일오버하지 않습니다. 차단이 당신의 콘텐츠와 정책의 속성이기 때문입니다 — 동일한 프롬프트를 다시 실행하면 다음 채널에서 그저 다시 차단되어 시도를 낭비할 뿐입니다.
guardrail_blocked를 당신의 클라이언트 재시도 루프에도 넣지 마세요. 그것은 결정적입니다: 동일한 정책에 대한 동일한 프롬프트는 매번 차단됩니다. 재시도는 바뀔 수 없는 결과를 위해 지연 시간을 태웁니다. 그것을 종단 거부로 취급하세요 — 입력을 고치거나, 정책을 고치세요.

​
5. 클라이언트 코드에서 처리하기

재시도하는 대신 code 필드로 분기하고 최종 사용자에게 유용한 메시지를 노출하세요. 
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()
여기 sk-orca-... 키는 릴레이 키입니다 — /v1/* 트래픽만 운반합니다. 그것으로 guardrail을 결코 편집하지 않습니다; 정책 작성과 연결은 당신의 세션에 대한 콘솔 / 관리 API 액션이며, guardrail을 생성하거나 편집하려면 Developer+ 역할이 필요합니다.

​
6. 차단 확인 및 튜닝

발동하는 모든 규칙은 — 차단 포함 — 그 타입, 액션, 스테이지, 그리고 상세 문자열과 함께 워크스페이스 Matches 피드에 안착합니다. 거기가 주어진 호출을 어느 규칙이 거부했는지 확인하고 거짓 양성을 분류하는 곳입니다.

Matches 피드

모든 block, mask, flag를 타입, 액션, 스테이지와 함께 봅니다. 매치된 부분 문자열은 Log raw content가 켜져 있을 때만 나타납니다.

로깅 및 프라이버시

원시 콘텐츠는 기본적으로 꺼져 있습니다 — 프라이버시 보수적 자세. 분류를 위해 부분 문자열이 필요할 때 guardrail별로 켜세요.

거짓 양성 튜닝

거짓 양성은 튜닝 신호이지 규칙을 비활성화할 이유가 아닙니다. 그것을 표시하고 패턴을 좁히세요.

버전 관리

정책을 변경했는데 되돌리고 싶나요? 임의의 두 버전을 diff하고 새 버전으로 되돌립니다 — 히스토리는 절대 변경되지 않습니다.
스트리밍 응답에서, 출력 block은 여전히 적용됩니다: 스캐너가 차단된 콘텐츠가 클라이언트에 도달하기 전에 스트림을 도중에 끊습니다. 출력 mask도 스트림에서 인밴드로 적용됩니다 — 스캐너가 안전한 접두사가 내보내지기 전에 롤링 버퍼에서 매치를 재작성합니다. 스트리밍 커버리지와 스트림 안전 규칙을 참조하세요.

​
7. 관련