예외¶

라이브러리가 발생시키는 예외입니다. 모두 KorailApiError를 상속합니다.

KorailApiError ¶

Bases: Exception

라이브러리가 발생시키는 모든 예외의 기반 클래스입니다.

except KorailApiError로 라이브러리 예외를 한꺼번에 처리할 수 있습니다. 라이브러리가 이 클래스 자체를 발생시키지는 않습니다. 아래 속성은 값이 없으면 None입니다.

code ¶

code: str | None = None

서버 결과 코드(h_msg_cd)입니다. 대기열 예외에서는 대기열 응답 코드입니다. 서버나 대기열의 응답 없이 발생한 예외에서는 None입니다.

message ¶

message: str | None = None

서버 결과 메시지(h_msg_txt)입니다. 대기열 예외에서는 라이브러리가 쓴 설명입니다. 없으면 None입니다.

raw ¶

raw: object | None = None

서버가 보낸 응답 원본입니다. 없으면 None입니다.

parser_raw ¶

parser_raw: object | None = None

응답 모델을 읽다가 실패했을 때 파서가 읽던 부분 원본입니다. 이때 raw에는 받은 응답 전체가 들어 있습니다. 없으면 None입니다.

KorailTransportError ¶

Bases: KorailApiError

네트워크 오류로 응답을 받지 못했거나, 서버가 2xx가 아닌 HTTP 상태로 응답했음을 나타냅니다.

리다이렉트는 따라가지 않으므로 3xx 응답도 이 예외가 됩니다. HTTP 상태 오류이면 raw에 응답 본문이 들어 있고, 네트워크 오류이면 원래의 httpx 예외가 __cause__에 들어 있습니다. 상태 변경 메서드에서 발생했다면 요청이 서버에 닿았는지 알 수 없으므로, 다시 호출하기 전에 예약 목록이나 승차권 목록으로 결과를 확인하세요.

KorailProtocolError ¶

Bases: KorailApiError

응답을 읽을 수 없거나 요청 전 입력 검사에 실패했음을 나타냅니다.

응답이 JSON 객체가 아니거나 필수 값이 없을 때, 닫힌 클라이언트로 요청하려 할 때도 발생합니다. 요청 전 입력 검사에서 발생했다면 요청은 보내지 않은 것입니다. 상태 변경 메서드가 응답을 읽지 못해 발생했다면 서버에서는 처리됐을 수 있으므로, 다시 호출하기 전에 결과를 확인하세요.

KorailAuthError ¶

KorailAuthError(
    *args: object,
    code: str | None = None,
    raw: object | None = None,
)

Bases: KorailApiError

로그인에 실패했거나, 로그인이 필요한 메서드를 로그인하지 않고 호출했음을 나타냅니다.

로그인에 실패하면 code에 로그인 응답의 결과 코드가, raw에 로그인 응답 원본이 들어 있습니다. 로그인하지 않았거나 세션에 고객번호가 없어 요청 전에 발생한 경우에는 code와 raw가 None이며, 요청은 보내지 않은 것입니다.

KorailSessionExpiredError ¶

KorailSessionExpiredError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailAuthError

서버 세션이 만료됐음을 나타냅니다.

실패 응답의 결과 코드가 P058일 때 발생합니다. 클라이언트는 이 예외를 발생시키기 전에 로컬 세션을 비웁니다. 계속하려면 login을 다시 호출해 로그인하세요.

KorailDynaPathError ¶

KorailDynaPathError(
    message: str | None = None, *, raw: object | None = None
)

Bases: KorailApiError

DynaPath 토큰을 붙이는 경로의 응답에서 차단 코드를 감지했음을 나타냅니다.

HTTP 상태와 봉투보다 먼저 판정하며, raw에 차단 코드가 든 응답이 들어 있습니다. 차단 코드가 들어 있는 응답 필드는 앱 내부 값이 공개돼 있지 않아 확인하지 못했습니다. 그래서 응답 최상위의 정수 값을 모두 검사하므로, 다른 필드의 같은 값도 차단으로 판정할 수 있습니다.

KorailAuthContinuationRequired ¶

KorailAuthContinuationRequired(
    redirect_url: str, *, raw: object | None = None
)

Bases: KorailAuthError

로그인을 마치려면 휴면 계정 해제나 비밀번호 변경 같은 웹 단계가 필요함을 나타냅니다.

로그인 응답의 결과 코드가 WRC000116 또는 WRC000420일 때 발생합니다. redirect_url에 서버가 준 웹 주소(없으면 "")가, code와 raw에 결과 코드와 로그인 응답 원본이 들어 있습니다. 라이브러리는 웹 단계를 대신 진행하지 않습니다.

KorailAppError ¶

KorailAppError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailApiError

서버가 실패로 응답했음을 나타냅니다.

결과 코드에 따라 하위 예외로 나뉘며, 어느 하위 예외에도 해당하지 않는 결과 코드는 이 클래스 그대로 발생합니다. code와 message에 결과 코드와 결과 메시지가, raw에 응답 원본이 들어 있습니다.

KorailNoResultsError ¶

KorailNoResultsError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailAppError

조회 조건에 맞는 결과가 없음을 나타냅니다. 결과 코드 WRG000000, P100, P114 등에서 발생합니다.

KorailNoDirectTrainError ¶

KorailNoDirectTrainError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailNoResultsError

직통 열차가 없음을 나타냅니다(결과 코드 WRD000061).

환승 여정은 search_transfer_trains로 조회하세요. search_trains_with_transfer_fallback은 이 예외가 발생했을 때만 환승 여정을 조회합니다.

KorailSoldOutError ¶

KorailSoldOutError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailAppError

매진됐거나 남은 좌석이 없음을 나타냅니다. 결과 코드 ERR211161, WRT300001 등에서 발생합니다.

KorailSeatUnavailableError ¶

KorailSeatUnavailableError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailAppError

지정한 좌석을 이용할 수 없음을 나타냅니다. 결과 코드 WRI411345 등에서 발생합니다.

KorailReservationRefusedError ¶

KorailReservationRefusedError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailAppError

중복 예약, 구매 한도, 예약 가능 시간 등의 이유로 예약이 거절됐음을 나타냅니다.

결과 코드 WRR800029, ERR911531 등에서 발생합니다.

KorailInvalidRequestError ¶

KorailInvalidRequestError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailAppError

서버가 입력값을 거절했음을 나타냅니다. 결과 코드 WRG200018, WRT100002 등에서 발생합니다.

KorailNotEntitledError ¶

KorailNotEntitledError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailAppError

할인이나 상품을 이용할 자격이 없음을 나타냅니다. 결과 코드 ERR299943, WRC000419 등에서 발생합니다.

KorailServiceUnavailableError ¶

KorailServiceUnavailableError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailAppError

서비스나 연결을 이용할 수 없다는 안내 응답을 나타냅니다(결과 코드 SEMGTK).

서버 장애만을 뜻하지는 않습니다. 로그인 응답이 이 결과 코드이면 KorailAuthError 대신 이 예외가 발생합니다.

KorailAppUpdateRequiredError ¶

KorailAppUpdateRequiredError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailAppError

앱 업데이트를 요구하는 응답을 나타냅니다(결과 코드 SUPDATE).

로그인 응답이 이 결과 코드이면 KorailAuthError 대신 이 예외가 발생합니다.

KorailNetFunnelError ¶

KorailNetFunnelError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailApiError

대기열을 통과하지 못해 API 요청을 보내지 않았음을 나타냅니다.

대기열 서버가 입장 키 없이 기다리라고 답했을 때, reserve·pay·reservation_view 관문에서 대기열 서버가 통과(200)로 답하지 않거나 대기열 서버 오류가 났을 때, 누적 대기 시간이 netfunnel_wait_limit를 넘었을 때 발생합니다. 대기열 응답으로 판정한 경우에는 code에 대기열 응답 코드가, raw에 대기열 응답이 들어 있습니다. 대기열 서버 오류로 요청을 보내지 않은 경우에는 code와 raw가 None이고 원래 예외가 __cause__에 들어 있습니다.

KorailQueueRejectedError ¶

KorailQueueRejectedError(
    code: str | None,
    message: str | None,
    *,
    raw: object | None = None,
)

Bases: KorailNetFunnelError

대기열 서버가 요청을 차단했음을 나타냅니다(대기열 응답 코드 301, 302).

모든 관문에서 발생하며, API 요청은 보내지 않은 것입니다. code에 대기열 응답 코드가, raw에 대기열 응답이 들어 있습니다.

KorailDynaPathRequiredError ¶

Bases: KorailApiError

DynaPath를 끈 설정으로 토큰이 필요한 요청(로그인)을 보내려 했음을 나타냅니다.

요청은 보내지 않습니다. 서버 응답의 차단 신호를 나타내는 KorailDynaPathError와 달리, 이 예외는 서버 응답을 받았다는 뜻이 아닙니다. 로그인하려면 DynaPath를 켠 설정(기본값)을 쓰세요.