오류

핵심 요약

오류가 발생하면 HTTP 상태 코드 → 서비스 오류 코드 → 해결 방법 순으로 확인하세요. Worker·Axum·SDK는 일부 오류 표현이 다릅니다.

보안 작업 거부를 정상 응답으로 바꾸지 말고 401, 403, 409, NOT_AVAILABLE을 각각 처리하세요.

오류 body는 백엔드가 구현한 곳에서 {code, message}를 가집니다 (선택적으로 error 아래 중첩); 내부 사유는 절대 노출되지 않습니다. 권위 있는 3컬럼 매트릭스(Axum be/ vs Worker vs SDK)는 계약 매트릭스 §2입니다 — 이 페이지는 운영 다이제스트입니다.

HTTP → 의미

상태	일반적 코드	의미
400	BAD_JSON/BAD_MSGPACK/BAD_PROTOBUF (Axum 코덱), VALIDATION, INVALID_PUBLIC_JWK (SDK)	잘못된 body 또는 필드
401	UNAUTHORIZED	인증/증명/바인딩/리플레이/body 해시 실패 — Worker와 SDK에서 모든 인증 검사에 하나의 불투명 코드
402	NOT_LIVE_PAYMENT, PAYMENT_PROVIDER_UNAVAILABLE	설정에 의해 결제 레일 거부(live 비활성 / 프로바이더 미구현)
403	FORBIDDEN, PRODUCT_MISMATCH, REVOKED, SUSPENDED, EXPIRED, INVALID_STATUS, DEVICE_LIMIT, CAPABILITY_INVALID (SDK), RESOURCE_FORBIDDEN (SDK), NOT_FOUND (Worker 활성화 거부)	게이트/소유권 거부
404	NOT_FOUND	없는 리소스 — 크로스 테넌트 행을 숨기는 데도 사용(fail closed)
409	CONFLICT, DEVICE_LIMIT (Axum 활성화), CAPABILITY_CONSUMED, IDEMPOTENCY_CONFLICT, ALREADY_REFUNDED	상태 충돌 / 중복 소비
413	PAYLOAD_TOO_LARGE (Worker) / BODY_TOO_LARGE (SDK)	body 제한 초과
429	bare 상태	전역 RPM 리미터; /auth/login은 5회 실패 → 5분 잠금 추가
500	TX, INTERNAL, CONFIG (SDK)	저장소/내부 실패, 설정 오류 — 항상 fail closed
503	PAYMENT_PROVIDER_UNAVAILABLE	프로바이더 어댑터 부재(Portone) 또는 도달 불가

의도적 Worker↔SDK 델타

이들은 버그가 아닌 문서화된 차이입니다 — code + HTTP 상태를 함께 읽으세요:

• VALIDATION (Worker) vs INVALID_PUBLIC_JWK (SDK) — 둘 다 400.
• FORBIDDEN (Worker) vs CAPABILITY_INVALID (SDK) — 둘 다 403.
• 403 NOT_FOUND(알 수 없는 키에 대한 Worker 활성화) vs 404 NOT_FOUND (SDK) — Worker는 라이선스 키 거부에 의도적으로 403을 반환합니다.
• PAYLOAD_TOO_LARGE vs BODY_TOO_LARGE — 둘 다 413.
• 알 수 없는 라이선스 status → INVALID_STATUS(Worker/Axum) vs REVOKED(SDK — 알 수 없는 상태는 절대 신뢰되지 않음).
• /licenses/execute/capability 가드 거부에서 INVALID_STATUS가 아닌 판정은 403 FORBIDDEN으로 축소됩니다; 구체적 코드는 license_blocked 보안 이벤트에만 남습니다.

웹 클라이언트 표면

@yetdapay/license-web은 {code}를 LicenseError.code에 그대로 전달하고 status는 실제 HTTP 상태입니다. @yetdapay/sdk는 같은 계약으로 YetdaPayError를 발생시킵니다.

CLI/MCP 표면

yp CLI는 HTTP 결과를 자체 계약으로 매핑합니다 — 인증 필요 명령의 401/403 → 로그인 힌트와 함께 exit 3; 다른 비-2xx → exit 1. MCP 도구 오류는 업스트림 {code,message}를 그대로 유지합니다.