SPECIFICATION
제 9 장: 에러 코드와 적합성 등급
본 장은 CAP 프로토콜의 표준화된 에러 코드 표, 그리고 구현이 적합성 등급을 선언하는 방식을 정의한다.
9.1 에러 코드 형식
에러 코드는 E_ 접두사의 대문자 언더스코어 명명을 사용한다. 에러 코드 문자열 자체가 규범적이다 — 본 사양의 구현은 MUST 본 장 정의에 따라 대응하는 에러 코드 문자열을 반환하여, 구현 간 일관된 진단을 가능하게 한다.
에러 응답 메시지 구조:
ErrorBody {
required error_code : string
required message : string
optional details : map<string, string>
optional retry_after_ms : uint32
}
| 필드 | 설명 |
|---|---|
error_code | 본 장에서 정의된 표준 에러 코드 |
message | 인간 가독 에러 기술(언어 고정 없음, 영어 또는 한국어 권장) |
details | 에러의 부가 컨텍스트(위반된 구체적 필드 등) |
retry_after_ms | 클라이언트 재시도 권장 대기 시간, 일시적 에러에만 의미 있음 |
9.2 자격 증명 관련 에러 코드
Authorization_Descriptor 및 Trusted_Ticket의 검증 실패 시나리오에 적용된다.
| 에러 코드 | HTTP 등가 | 발동 조건 | 적합성 |
|---|---|---|---|
E_DESCRIPTOR_NOT_FOUND | 404 | 참조된 descriptor_id를 단말 로컬에서 찾을 수 없음 | 단말 MUST |
E_INVALID_STRUCTURE | 400 | 자격 증명 구조가 §2.3 / §2.4에 부합하지 않음 | 단말/발급자 MUST |
E_INVALID_SIGNATURE | 401 | 서명 검증 실패 | 단말 MUST |
E_VERIFICATION_KEY_INVALID | 401 | 서명 key_id에 대응하는 Verification_Key가 미등록 또는 폐기됨 | 단말 MUST |
E_UNKNOWN_ISSUER | 401 | 자격 증명의 issuer_id가 단말 신뢰 목록에 없음 | 단말 MUST |
E_DESCRIPTOR_REVOKED | 403 | Authorization_Descriptor가 폐기됨 | 단말 MUST |
E_TICKET_REVOKED | 403 | Trusted_Ticket이 폐기됨 | 단말 MUST |
E_DESCRIPTOR_EXPIRED | 403 | 자격 증명이 not_after를 경과 | 단말 MUST |
E_DESCRIPTOR_NOT_YET_VALID | 403 | 현재 시각이 not_before보다 빠름 | 단말 MUST |
E_TICKET_MALFORMED | 400 | JWS 파싱 실패 또는 typ 부정확 | 단말 MUST |
E_DUPLICATE_DESCRIPTOR_ID | 409 | 제출된 자격 증명이 이미 보관된 자격 증명 ID와 충돌하며 내용 불일치 | 단말 MUST |
E_VALIDITY_OUT_OF_RANGE | 400 | 자격 증명의 not_after - not_before가 제한 초과 | 단말/발급자 MUST |
E_REVOCATION_QUERY_TIMEOUT | 504 | 온라인 폐기 조회 타임아웃 | 단말 SHOULD |
9.3 인가 범위 에러 코드
자격 증명이 합법적이지만 인가 범위가 매칭되지 않는 시나리오에 적용된다.
| 에러 코드 | HTTP 등가 | 발동 조건 |
|---|---|---|
E_SUBJECT_MISMATCH | 403 | 자격 증명 subject가 요청자 fay_id와 불일치 |
E_TERMINAL_MISMATCH | 403 | 자격 증명 terminal_id가 현재 단말과 불일치 |
E_AUTHORIZATION_INSUFFICIENT | 403 | (resource, mode)에 매칭되는 Grant를 찾을 수 없음 |
E_RATE_LIMIT_EXCEEDED | 429 | constraints의 빈도 제한 초과 |
E_OUT_OF_TIME_WINDOW | 403 | 현재 시각이 constraints 시간 윈도우 외 |
E_OUT_OF_GEO_FENCE | 403 | 단말 위치가 constraints 지리 펜스 외 |
E_UNSUPPORTED_CONSTRAINT | 400 | 자격 증명이 미식별 constraint 키를 포함 |
9.4 리소스와 세션 에러 코드
리소스 점유, Session 상태 관련 에러에 적용된다.
| 에러 코드 | HTTP 등가 | 발동 조건 |
|---|---|---|
E_RESOURCE_BUSY | 409 | 리소스가 요청 모드에서 이미 점유됨(읽기-쓰기 잠금 매트릭스 위반) |
E_RESOURCE_UNAVAILABLE | 503 | 리소스 현재 사용 불가(하드웨어 분리, 소프트웨어 미실행 등) |
E_RESOURCE_NOT_FOUND | 404 | resource_id가 존재하지 않음 |
E_SESSION_NOT_FOUND | 404 | session_id가 존재하지 않음 |
E_SESSION_TERMINATED | 410 | Session이 종료됨, 작업 계속 불가 |
E_SESSION_LIMIT_EXCEEDED | 429 | §5.8 정의의 Session 수량 제한 초과 |
E_OS_INTEGRATION_FAILED | 500 | OS 접근 제어 하달 실패 |
9.5 인계 관련 에러 코드
제 6 장에서 정의된 인계 흐름에 적용된다.
| 에러 코드 | HTTP 등가 | 발동 조건 |
|---|---|---|
E_HANDOVER_INVALID_SOURCE | 400 | source_session_id가 존재하지 않거나 상태가 인계를 허용하지 않음 |
E_HANDOVER_INVALID_TARGET | 400 | target_credential 검증 실패 |
E_HANDOVER_REJECTED_BY_POLICY | 403 | 정책 평가가 인계 거부 |
E_HANDOVER_FAILED_AT_RELEASE | 500 | 인계 과정 중 소스 Session 해제 실패 |
E_HANDOVER_FAILED_AT_ACQUIRE | 500 | 인계 과정 중 대상 Session 생성 실패 |
E_HANDOVER_TIMEOUT | 504 | 인계 타임아웃 |
E_HANDOVER_IN_PROGRESS | 409 | 리소스에 진행 중인 인계 있음, 새 요청 거부 |
E_HANDOVER_RETRY_LIMIT | 429 | 재시도 횟수가 제한 초과 |
9.6 프로토콜과 시스템 에러 코드
| 에러 코드 | HTTP 등가 | 발동 조건 |
|---|---|---|
E_PROTOCOL_VERSION_UNSUPPORTED | 400 | 메시지 version 필드가 구현에 의해 지원되지 않음 |
E_INVALID_MESSAGE | 400 | 프로토콜 메시지 형식이 §2.6에 부합하지 않음 |
E_INTERNAL_ERROR | 500 | 단말 내부 에러(세부사항 노출하지 않음) |
E_NOT_IMPLEMENTED | 501 | 구현이 해당 옵션 능력을 제공하지 않음 |
E_STORAGE_FULL | 507 | 단말 자격 증명 보관 만 |
9.7 에러 코드 확장
구현은 MAY 커스텀 에러 코드를 정의할 수 있지만, MUST:
E_VENDOR_<vendor_name>_<code>명명 형식 사용(E_VENDOR_ACME_QUOTA_EXCEEDED등)- 본 장에서 정의된 표준 에러 코드와 충돌하지 않음
- 구현 문서에서 시맨틱을 명시함
iFay_Runtime은 미식별 커스텀 에러 코드 수신 시 SHOULD E_INTERNAL_ERROR로 처리한다.
9.8 적합성 등급 선언
구현은 MUST 다음 방식으로 충족하는 적합성 등급을 선언한다.
9.8.1 적합성 선언 구조
ConformanceClaim {
required protocol_version : string // "1.0.0" 또는 "draft" 등
required levels : array<ConformanceLevel> (len 1..3)
optional optional_features : array<string>
optional vendor_extensions : array<string>
}
ConformanceLevel = enum["terminal", "issuer", "runtime"]
| 필드 | 설명 |
|---|---|
protocol_version | 구현이 준수하는 CAP 프로토콜 버전 번호 |
levels | 구현이 충족하는 적합성 등급(§0.5 참조) |
optional_features | 구현이 지원하는 옵션 능력(aggregated_heartbeat, ai_model_handover_policy 등) |
vendor_extensions | 구현이 지원하는 벤더 확장 능력 |
9.8.2 선언 게시 채널
구현은 SHOULD 다음 채널로 ConformanceClaim을 게시한다:
- 제품 문서에서 명시적 선언
- 특정 조회 인터페이스로 반환(구체적 인터페이스는 구현으로 정의)
- SDK 패키지 메타데이터에서 선언
9.8.3 적합성 테스트
CAP 프로토콜의 적합성 테스트 스위트(Conformance Test Suite)는 보조 자산으로서 프로젝트가 유지하지만, 본 사양의 규범적 범위에 포함되지 않는다. 임의의 구현은 SHOULD 대응하는 적합성 등급의 테스트 스위트를 통과하지만, MUST 테스트 스위트를 정확성의 유일한 보장으로 의존하지 않는다.
9.9 에러 코드 사용 권장
구현은 SHOULD 다음 에러 코드 사용 원칙을 따른다:
- 가장 구체적인 에러 코드를 우선 선택: 예를 들어
E_TICKET_REVOKED는E_TICKET_MALFORMED보다 우선(둘이 분석 과정에서 출현 가능성이 있는 경우라도) - 에러 코드를 통해 내부 세부사항을 노출하지 않음: 에러 message 필드에서 키 핑거프린트, 내부 ID 등 민감 정보 노출 회피
- details 필드로 진단 보조 제공: 예를 들어
details["field"] = "not_after"로 구체적으로 어떤 필드가 부적합한지를 나타냄 - 일시적 에러는 retry_after_ms 사용: 예를 들어
E_RESOURCE_BUSY,E_HANDOVER_IN_PROGRESS
9.10 에러 코드와 schema.json의 동기화
schema/{version}/schema.json은 MUST 완전한 에러 코드 열거 정의를 포함하며, 본 장과 일관성을 유지한다. 본 장의 에러 코드 목록 갱신 시, schema.json은 MUST 동기 갱신된다.