errors.py

"""NHPLUG 공통 오류 모델.

🔴 **업무 오류는 이 예외로 올라오지 않는다.** SDK 는 업무 성공/실패를 판정하지 않는다.
HTTP 200 이면 본문을 그대로 돌려주므로, 서버가 `rsp_msg` 로 무엇을 말했는지는
**호출자가 읽고 판단**한다(`nhplug.status_of()`).

이 예외가 나는 경우는 **HTTP 200 이 아닐 때**(전송·인증·유량)뿐이다.
서버 본문은 가공 없이 `.raw` 에 담겨 있다 — 업무 서식(`rsp_cd`/`rsp_msg`)이든
게이트웨이 서식(`error_code`/`error_description`)이든 원문 그대로다.
"""


class NhplugError(Exception):
    """NH Open API 호출 실패.

    category:
      - "config"     : 설정 오류 — 호출하기 전에 막은 것 (허용되지 않은 호스트, https 아님 …)
      - "auth"       : 토큰 발급/인증 실패 (IGW40031, IGW40043, 401 …)
      - "rate_limit" : 호출 유량 초과 (429, IGW42902)
      - "network"    : 네트워크/타임아웃
      - "http"       : 그 외 HTTP 오류 (200 이 아닌 모든 응답)

    ⚠️ "business" 카테고리는 **0.4.0 에서 없어졌다.** HTTP 200 응답은 예외가 되지 않는다.
    """

    def __init__(
        self,
        message: str,
        *,
        category: str = "http",
        code: str | None = None,
        status: int | None = None,
        path: str | None = None,
        retryable: bool = False,
        retry_after_ms: int | None = None,
        environment: str | None = None,
        raw=None,
    ):
        super().__init__(message)
        self.message = message
        self.category = category
        self.code = code                    # rsp_cd 또는 IGW… 코드
        self.status = status                # HTTP 상태코드
        self.path = path                    # 호출 경로
        self.retryable = retryable          # 재시도 의미가 있는가(자동 재시도는 하지 않음)
        self.retry_after_ms = retry_after_ms
        self.environment = environment      # 호출 대상 base url
        self.raw = raw                      # 서버 원본 응답(dict 또는 문자열)

    def __str__(self) -> str:
        parts = [f"[{self.category}]"]
        if self.code:
            parts.append(str(self.code))
        parts.append(self.message)
        if self.path:
            parts.append(f"({self.path})")
        if self.retry_after_ms:
            parts.append(f"retry_after={self.retry_after_ms}ms")
        return " ".join(parts)