"""카페24 연동 공통 예외. 라우터/서비스는 httpx 예외를 직접 다루지 않고 여기 정의된 타입만 잡는다. 모든 메시지는 사용자에게 그대로 노출될 수 있으므로 토큰/시크릿을 담지 않는다. """ from __future__ import annotations class Cafe24Error(Exception): """카페24 연동 최상위 예외.""" class Cafe24ConfigError(Cafe24Error): """CAFE24_* 환경변수 미설정 등 설정 문제.""" class Cafe24AuthError(Cafe24Error): """인증 실패 — 토큰 없음/만료/refresh 불가. 재인증이 필요하다.""" def __init__(self, message: str, *, needs_reauth: bool = False): super().__init__(message) self.needs_reauth = needs_reauth class Cafe24RateLimitError(Cafe24Error): """429 Too Many Requests. retry_after 초 뒤 재시도 가능.""" def __init__(self, message: str, *, retry_after: float = 1.0): super().__init__(message) self.retry_after = retry_after class Cafe24FtpError(Cafe24Error): """디자인 보관함 FTP 연결/전송 실패 (product-swiper.js 편집 등). maybe_applied: 원본 경로가 이미 새 내용으로 바뀌었을 수 있다(교체 뒤 확인 단계 실패). False 면 원본은 그대로다(임시 파일 단계에서 멈춤). """ def __init__(self, message: str, *, maybe_applied: bool = False): super().__init__(message) self.maybe_applied = maybe_applied class Cafe24FtpConflict(Cafe24FtpError): """교체 직전 다시 읽은 원본이 편집 시작 때와 다르다 — 남의 수정을 덮지 않고 멈춘다.""" class Cafe24ApiError(Cafe24Error): """그 외 API 오류(4xx/5xx). status 로 재시도 가능 여부를 판단한다. maybe_applied: 쓰기 요청(PUT/POST/DELETE)이 카페24에 **도달했을 수도** 있는가. 응답을 받기 전에 끊겼거나(읽기 타임아웃 등) 5xx 를 받은 시도가 한 번이라도 있으면 True — 반영됐는지 모르므로 호출부는 재적용하지 말고 "확인 필요"로 둔다. 연결 자체가 안 된 경우(ConnectError)와 4xx 는 반영되지 않은 것이 확실하다. """ def __init__(self, message: str, *, status: int = 0, endpoint: str = "", maybe_applied: bool = False): super().__init__(message) self.status = status self.endpoint = endpoint self.maybe_applied = maybe_applied @property def retryable(self) -> bool: """5xx 와 타임아웃(status=0)만 재시도 대상. 4xx 는 고쳐야 할 요청.""" return self.status == 0 or self.status >= 500