PCL ReasonCode
PCL이 정책 평가에 실패한 트랜잭션을 거절할 때 발행하는 표준 코드. 지갑과 미들웨어가 이 코드로 UX 분기.
PCL이 트랜잭션을 거절할 때, 거절 사유는 자유 텍스트가 아니라 표준 코드로 노출됩니다. 지갑, 에이전트 SDK, dapp UI가 실패를 일관되게 해석하고 (적절한 경우) 자동 복구 흐름으로 연결할 수 있게 합니다 — 예를 들어 EasAttestationRequired가 반환되면 사용자에게 KYC 완료를 안내. 코드는 안정적 식별자입니다. 새 정책 템플릿이 도입될 때 새 코드가 추가되지만, 기존 코드의 이름 변경이나 의미 재사용은 없습니다.
V1 ReasonCode 셋
| ReasonCode | 의미 | 발생 조건 |
| :--- | :--- | :--- |
|
|
|
|
|
|
|
|
| :--- | :--- | :--- |
|
InDenylist | 차단 주소 | 송신자 또는 수신자가 DENYLIST_POLICY 목록에 존재 ||
EasAttestationRequired | 필요한 EAS attestation 미보유 | EAS_POLICY가 요구하는 schema를 송신자가 보유하지 않음 (또는 attestation 만료/폐기됨) ||
VolumeAboveMaxLimit | 건당 금액 상한 초과 | VOLUME_POLICY의 max_limit 초과 ||
VolumeBelowMinLimit | 건당 금액 하한 미달 | VOLUME_POLICY의 min_limit 미달 ||
PeriodicVolumeAboveLimit | 주기별 누적 한도 초과 | PERIODIC_VOLUME_POLICY 또는 OKRW_EAS_PERIODIC_VOLUME_LIMIT_POLICY 윈도우 소진 ||
Unauthorized | 권한 없음 | 정책 변경 호출자가 PolicyAdmin (전역) 또는 컨트랙트 admin (컨트랙트별)이 아님 ||
PolicyAlreadyRegistered | 중복 등록 | 이미 정책 entry가 있는 컨트랙트에 대해 register 호출 ||
UnknownPolicyType | 미등록 템플릿 | UnitPolicy.template_id가 이 네트워크에 등록되지 않은 enum 값을 참조 |지갑 / SDK 처리 방법
ReasonCode를 기계 읽기 레이어로 취급하세요. PCL이 함께 반환할 수 있는 사람 읽기 문자열이 아니라 코드로 UX를 분기하세요. 예시:
MAWS의
EasAttestationRequired→ KYC 파트너의 온보딩 흐름 트리거.InDenylist→ 종결 거절; 재시도 옵션 없이 "이 주소는 거래 불가" 표시.VolumeAboveMaxLimit/VolumeBelowMinLimit→ 분할 전송 또는 금액 조정 제안.PeriodicVolumeAboveLimit→ "일/월 한도 도달; <다음 윈도우>에 초기화" 표시.Unauthorized/PolicyAlreadyRegistered/UnknownPolicyType→ 관리자 툴 에러; 관리자 UI에 raw로 노출, 최종 사용자 UI에서는 숨김.
MAWS의
policy.preflight도 동일한 ReasonCode 형태를 반환합니다 — 에이전트가 transfer.send 전에 호출해 거절될 트랜잭션의 가스 낭비를 피합니다.새 코드 추가
새
PolicyTemplate이 등록될 때 (네트워크 업그레이드) 하나 이상의 새 ReasonCode가 함께 추가됩니다. 코드 식별자는 실패를 설명하는 CamelCase로 작명됩니다 (예: 향후 JurisdictionMismatch는 가상의 관할권 체크 템플릿에 매핑). 오래된 코드는 사라지지 않습니다 — 그 코드가 나온 템플릿이 폐기되더라도, 코드는 유지되어 과거 트랜잭션 실패를 해석할 수 있게 합니다.