auto-trade/common-docs/api-reference/kis-error-code-reference.md

KIS 오류코드 적용 기준 (2026-02-26)

1) 기준 소스

• 공식 오류코드 페이지: https://apiportal.koreainvestment.com/faq-error-code
• 확인 방식: 실제 브라우저 렌더링 후 테이블 추출
• 코드 반영 위치: lib/kis/error-codes.ts

2) 코드 반영 목적

• msg_cd만 보일 때 의미를 바로 알기 어렵기 때문에, 코드와 문구를 같이 표시해 장애 원인 파악 속도를 높입니다.
• 토큰 발급/폐기, REST 호출, 웹소켓 제어 오류 메시지의 형식을 통일합니다.

3) 적용된 모듈

• lib/kis/error-codes.ts
  • 공식 FAQ 코드 문구 매핑
  • getKisErrorGuide(msgCode) 제공
  • buildKisErrorDetail(...) 제공
• lib/kis/client.ts
  • REST 실패 메시지에 msg_cd + 공식 문구 반영
• lib/kis/token.ts
  • 토큰 발급/폐기 실패 메시지에 msg_cd + 공식 문구 반영
• lib/kis/approval.ts
  • 승인키 발급 실패 메시지에 msg_cd + 공식 문구 반영
• features/kis-realtime/stores/kisWebSocketStore.ts
  • 실시간 제어 오류(OPSP*) 메시지에 공식 문구 반영

4) 운영 시 참고

• 화면/로그에 EGW00103, OPSP8996처럼 코드가 보이면 lib/kis/error-codes.ts에서 즉시 문구를 확인할 수 있습니다.
• 신규 코드가 추가되면 공식 FAQ 기준으로 맵에 추가합니다.