본문으로 건너뛰기

일반 에러 처리

개요​

이 문서는 QA Agent 사용 중 발생할 수 있는 일반적인 에러와 그 해결 방법을 설명합니다.

에러 분류​

1. 시스템 레벨 에러​

1.1 연결 오류​

에러 코드: QA_CONN_001

{
  "code": "QA_CONN_001",
  "message": "CONNECTION_TIMEOUT",
  "detail": "Failed to connect to QA Agent service",
  "timestamp": 1679471431000
}

원인:

  • 네트워크 연결 문제
  • QA Agent 서비스 다운
  • 방화벽 차단

해결 방법:

  1. 네트워크 연결 상태 확인
  2. QA Agent 서비스 상태 확인: curl https://qa-agent-{env}.sleepq.ai/v1/health
  3. 방화벽 설정 확인
  4. 재시도 로직 구현

1.2 인증 오류​

에러 코드: QA_AUTH_001

{
  "code": "QA_AUTH_001",
  "message": "UNAUTHORIZED",
  "detail": "Invalid or expired authentication token",
  "timestamp": 1679471431000
}

원인:

  • 토큰 만료
  • 잘못된 토큰
  • 권한 부족

해결 방법:

  1. 토큰 갱신
  2. 올바른 토큰 사용 확인
  3. 필요한 권한 확인

2. 리소스 관련 에러​

2.1 리소스 부족​

에러 코드: QA_RES_001

{
  "code": "QA_RES_001",
  "message": "RESOURCE_EXHAUSTED",
  "detail": "Insufficient resources to execute test",
  "metadata": {
    "requestedCpu": "4",
    "availableCpu": "2",
    "requestedMemory": "8GB",
    "availableMemory": "4GB"
  }
}

원인:

  • CPU/메모리 부족
  • 동시 실행 한계 초과
  • 디스크 공간 부족

해결 방법:

  1. 리소스 요구사항 조정
  2. 병렬 실행 수준 감소
  3. 리소스 정리 후 재시도

2.2 Rate Limiting​

에러 코드: QA_RATE_001

{
  "code": "QA_RATE_001",
  "message": "RATE_LIMIT_EXCEEDED",
  "detail": "Too many requests",
  "retryAfter": 60
}

원인:

  • API 호출 한도 초과
  • 단시간 내 과도한 요청

해결 방법:

  1. 지수 백오프 구현
  2. 요청 간격 조정
  3. 배치 처리 활용

3. 데이터 관련 에러​

3.1 데이터 유효성 검증 실패​

에러 코드: QA_DATA_001

{
  "code": "QA_DATA_001",
  "message": "INVALID_DATA",
  "detail": "Request data validation failed",
  "errors": [
    {
      "field": "userId",
      "message": "Invalid user ID format"
    },
    {
      "field": "startTime",
      "message": "Start time must be before end time"
    }
  ]
}

원인:

  • 잘못된 데이터 형식
  • 필수 필드 누락
  • 데이터 제약 조건 위반

해결 방법:

  1. 입력 데이터 검증
  2. 데이터 형식 확인
  3. API 문서 참조

3.2 데이터 없음​

에러 코드: QA_DATA_404

{
  "code": "QA_DATA_404",
  "message": "DATA_NOT_FOUND",
  "detail": "Requested data does not exist",
  "metadata": {
    "entity": "TestRun",
    "id": "run-12345"
  }
}

원인:

  • 존재하지 않는 리소스 조회
  • 데이터 삭제됨
  • 잘못된 ID 사용

해결 방법:

  1. 리소스 ID 확인
  2. 데이터 존재 여부 검증
  3. 삭제된 데이터 복구 검토

에러 처리 전략​

1. 재시도 전략​

1.1 지수 백오프​

async function retryWithBackoff(fn, maxRetries = 3) {
  let lastError;

  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;

      if (i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await sleep(delay);
      }
    }
  }

  throw lastError;
}

1.2 조건부 재시도​

function shouldRetry(error) {
  const retryableCodes = ['QA_CONN_001', 'QA_RATE_001', 'QA_RES_001'];

  return retryableCodes.includes(error.code);
}

2. 에러 로깅​

2.1 구조화된 로깅​

function logError(error, context) {
  const errorLog = {
    timestamp: Date.now(),
    level: 'ERROR',
    service: 'qa-agent-client',
    error: {
      code: error.code,
      message: error.message,
      detail: error.detail,
      stack: error.stack,
    },
    context: {
      userId: context.userId,
      testRunId: context.testRunId,
      action: context.action,
    },
  };

  console.error(JSON.stringify(errorLog));
}

2.2 에러 집계​

class ErrorAggregator {
  constructor() {
    this.errors = new Map();
  }

  add(error) {
    const key = `${error.code}_${error.message}`;
    const count = this.errors.get(key) || 0;
    this.errors.set(key, count + 1);
  }

  getTopErrors(limit = 10) {
    return Array.from(this.errors.entries())
      .sort((a, b) => b[1] - a[1])
      .slice(0, limit);
  }
}

3. 에러 알림​

3.1 임계값 기반 알림​

const errorThresholds = {
  QA_AUTH_001: { count: 10, window: 300000 }, // 5분 내 10회
  QA_RES_001: { count: 5, window: 600000 }, // 10분 내 5회
  QA_DATA_001: { count: 20, window: 300000 }, // 5분 내 20회
};

3.2 에스컬레이션​

  • Level 1: 로그 기록
  • Level 2: 이메일 알림
  • Level 3: SMS/전화 알림
  • Level 4: 인시던트 생성

복구 절차​

1. 자동 복구​

  • 재시도 메커니즘
  • 폴백 전략
  • 자가 치유

2. 수동 개입​

  • 관리자 알림
  • 수동 재시작
  • 데이터 복구

모범 사례​

  1. 에러 예방

    • 입력 검증 강화
    • 리소스 모니터링
    • 예외 처리 구현

  2. 빠른 감지

    • 실시간 모니터링
    • 이상 탐지
    • 헬스체크

  3. 효과적인 대응

    • 명확한 에러 메시지
    • 상세한 로깅
    • 신속한 알림

  4. 지속적 개선

    • 에러 패턴 분석
    • 근본 원인 해결
    • 예방 조치 구현

관련 문서​