이 페이지는 자동 번역되었습니다. 영어 원문이 정본입니다. 영어로 읽기 →
메인 콘텐츠로 건너뛰기

장애 대응 플레이북

자주 발생하는 문제에 대한 대응 절차입니다.

연결 문제​

WebSocket 연결 끊김​

증상: WebSocket 연결이 끊기고 메시지가 수신되지 않습니다

조치:

  1. 지수 백오프 방식의 자동 재연결을 구현합니다
  2. REST 엔드포인트를 폴링하여 놓친 업데이트를 따라잡습니다
  3. 재연결 후 모든 채널을 다시 구독합니다

예방: 연결 상태를 모니터링하고 견고한 재연결 로직을 구현합니다

API 타임아웃​

증상: REST 요청이 타임아웃되거나 5xx 오류를 반환합니다

조치:

  1. 지수 백오프 방식으로 재시도합니다
  2. 헬스 엔드포인트를 확인합니다: GET /health
  3. 시스템이 과부하 상태이면 요청 빈도를 줄입니다

예방: 요청 스로틀링과 서킷 브레이커를 구현합니다

주문 문제​

높은 주문 거부율​

증상: 많은 주문이 거부됩니다

조사:

  1. 모든 주문 응답과 WebSocket order_updates 메시지의 status 및 reason을 기록합니다. GET /orders?wallet=...는 기본적으로 미체결 주문을 반환하며 거부 사유를 포함하지 않습니다
  2. 증거금을 검토합니다: GET /portfolio?wallet=...
  3. 계정 한도를 확인합니다: GET /risk/limits?wallet=...
  4. 상품이 만기되지 않았는지 확인합니다: GET /instruments?currency=...

조치:

  • 증거금 문제인 경우: 포지션 규모를 줄이거나 담보를 추가합니다
  • 등급(tier) 문제인 경우: 매도를 롱 보유 물량으로 커버하거나, 등급 변경에 대해 Hypercall에 문의합니다
  • 만기된 경우: 다른 상품을 사용합니다

체결 누락​

증상: 주문은 체결되었으나 체결 알림이 오지 않습니다

조사:

  1. GET /fills?wallet=...에서 체결 내역을 확인합니다
  2. WebSocket fills 채널 구독을 확인합니다
  3. WebSocket 연결 상태를 확인합니다

조치:

  • fills 채널을 다시 구독합니다
  • REST 엔드포인트를 폴링하여 누락된 체결을 조회합니다
  • 체결 내역을 주문 상태와 대사합니다

오래된 주문 상태​

증상: REST의 주문 상태가 WS와 일치하지 않습니다

조사:

  1. WebSocket 연결 상태를 확인합니다
  2. 주문 캐시가 최신 상태인지 확인합니다
  3. REST와 WS의 주문 상태를 비교합니다

조치:

  • WS 재연결 후 REST를 폴링하여 상태를 따라잡습니다
  • 대사 시 REST를 기준 데이터로 사용합니다

MMP 문제​

MMP가 너무 자주 발동됨​

증상: 많은 주문이 MMP에 의해 취소됩니다

조사:

  1. 서명된 GET /mmp-config?wallet=...&currency=...로 MMP 설정을 확인합니다
  2. 체결 패턴과 누적 지표를 검토합니다
  3. 한도가 너무 낮게 설정되어 있는지 확인합니다

조치:

  • MMP 한도(qty, delta, vega)를 높입니다
  • interval_ms를 늘려 윈도우 내에서 더 많은 체결을 허용합니다
  • 호가 제시 빈도를 줄입니다

MMP가 발동되지 않음​

증상: 체결이 한도를 초과했는데도 MMP가 발동되지 않습니다

조사:

  1. 서명된 GET /mmp-config?wallet=...&currency=...로 MMP가 활성화되어 있는지 확인합니다
  2. 주문에 mmp_enabled=true가 설정되어 있는지 확인합니다
  3. 통화가 주문의 기초자산과 일치하는지 확인합니다

조치:

  • 주문에서 MMP를 활성화합니다: mmp_enabled=true
  • 올바른 통화에 대해 MMP를 설정합니다
  • 필요하면 한도를 조정합니다

서명된 MMP 조회 요청은 GetMmpConfig 만료 시각과 서명을 X-Hypercall-Expires-At-Ms 및 X-Hypercall-Signature 헤더로 전송합니다.

증거금 문제​

증거금 부족​

증상: 주문이 "Insufficient margin" 사유로 거부됩니다

조사:

  1. 포트폴리오를 확인합니다: GET /portfolio?wallet=...
  2. 증거금 계산을 검토합니다
  3. 어떤 시나리오에서 실패하는지 확인합니다

조치:

  • 포지션 규모를 줄입니다
  • 담보를 추가합니다
  • 포지션을 청산하여 증거금을 확보합니다
  • 익스포저를 헤지하여 최악의 경우 손실을 줄입니다

현물 가격 누락​

증상: 주문이 "Missing spot price for underlying"으로 시작하는 사유로 거부됩니다

조사:

  1. GET /markets에서 해당 기초자산의 index_price를 확인합니다
  2. 기초자산 심볼이 올바른지 확인합니다
  3. 상태 페이지에서 오라클 장애 여부를 확인합니다

조치:

  • 현물 가격 피드가 복구될 때까지 기다립니다
  • 가능하면 다른 기초자산을 사용합니다
  • 문제가 지속되면 지원팀에 문의합니다

시스템 문제​

높은 지연 시간​

증상: API 응답이 느리거나 WebSocket 메시지가 지연됩니다

조사:

  1. 시스템 부하를 확인합니다
  2. 응답 시간을 모니터링합니다
  3. 네트워크 연결 상태를 확인합니다

조치:

  • 요청 빈도를 줄입니다
  • 요청 스로틀링을 구현합니다
  • 문제가 지속되면 지원팀에 문의합니다

요청 빈도 제한​

증상: 요청이 거부되거나 스로틀링됩니다

현재 정책: 요청 빈도 제한은 지갑별로 적용되며, 취소, 에이전트 승인, MMP 쓰기, 리스크 시뮬레이션에는 요청 출처별 한도가 별도로 적용됩니다. 자세한 내용은 요청 빈도 제한을 참고하세요.

조치:

  • Retry-After 헤더를 확인하고 재시도 전에 대기합니다
  • X-RateLimit-Remaining을 모니터링하여 한도 도달을 방지합니다
  • 가능하면 일괄(bulk) 엔드포인트를 사용합니다

긴급 절차​

킬 스위치​

즉시 조치:

  1. 모든 주문을 취소합니다: DELETE /bulk_order 또는 DELETE /bulk_order_cloid, 요청당 최대 50개 주문
  2. WebSocket 연결을 끊습니다
  3. 호가 제시 시스템을 중지합니다

복구:

  1. 모든 주문이 취소되었는지 확인합니다: GET /orders?wallet=...
  2. 포트폴리오를 검토합니다: GET /portfolio?wallet=...
  3. 근본 원인을 조사합니다
  4. 문제가 해결된 후 호가 제시를 재개합니다

데이터 대사​

장애 이후:

  1. REST 엔드포인트를 폴링하여 현재 상태를 조회합니다
  2. 주문을 대사합니다: GET /orders?wallet=...
  3. 체결을 대사합니다: GET /fills?wallet=...
  4. 포트폴리오를 대사합니다: GET /portfolio?wallet=...
  5. WebSocket 구독을 재개합니다

에스컬레이션​

문제가 지속되는 경우:

  1. 접근 권한과 함께 제공된 알려진 이슈 및 스테이징 공지를 검토합니다
  2. 자세한 절차는 런북을 확인합니다
  3. 다음 정보와 함께 지원팀에 문의합니다:
    • 지갑 주소
    • 오류 메시지
    • 타임스탬프
    • 재현 단계
최종 업데이트: