외부 API 실패에 대비하세요

네트워크 지연, 제공자의 점검, 호출 한도 초과 등 다양한 이유로 API 요청은 실패할 수 있습니다. 안정적인 서비스는 실패하지 않는 서비스가 아니라 실패를 예측하고 적절히 복구하는 서비스입니다.

기본 대응 방법

• 요청에 적절한 타임아웃을 설정합니다.
• 일시적인 오류는 지수 백오프 방식으로 재시도합니다.
• 429 Too Many Requests 응답과 호출 제한 헤더를 확인합니다.
• 동일한 요청을 반복하지 않도록 결과를 캐시합니다.
• 장애 상황에서도 사용할 수 있는 기본 화면과 안내 문구를 준비합니다.

오류 로그에는 요청 시간, 상태 코드와 추적 가능한 식별자를 남기되 API Key나 개인정보는 기록하지 않아야 합니다.

오류를 종류별로 구분하세요

모든 실패를 같은 방식으로 처리하면 불필요한 재시도가 늘어나고 장애가 더 커질 수 있습니다. 상태 코드와 실패 원인에 따라 대응 방법을 구분해야 합니다.

• 요청 오류: 잘못된 파라미터나 인증 정보는 재시도하지 않고 입력과 설정을 수정합니다.
• 호출 제한: 제공자가 안내한 대기 시간 이후 다시 요청합니다.
• 서버 오류: 짧은 간격의 반복 요청을 피하고 제한된 횟수만 재시도합니다.
• 네트워크 오류: 타임아웃과 연결 실패를 구분하고 사용자에게 현재 상태를 안내합니다.

응답 본문에 제공자 고유의 오류 코드가 포함된다면 상태 코드와 함께 저장해 원인을 더 정확히 파악할 수 있습니다.

재시도 정책 만들기

재시도는 일시적인 장애를 복구하는 데 유용하지만 요청이 몰린 상황에서는 제공자 서버에 더 큰 부담을 줄 수 있습니다. 첫 재시도는 짧게 시작하되 이후 대기 시간을 점차 늘리고 무작위 지연을 더하는 것이 안전합니다.

1. 읽기 요청처럼 반복해도 결과가 안전한 요청인지 확인합니다.
2. 최대 재시도 횟수와 전체 제한 시간을 정합니다.
3. 재시도할 상태 코드와 즉시 실패할 상태 코드를 구분합니다.
4. 최종 실패 시 사용자 화면과 운영 알림을 준비합니다.

결제나 데이터 생성 요청은 동일한 요청이 중복 처리되지 않도록 멱등성 키를 지원하는지 확인해야 합니다.

캐시와 대체 데이터 활용

자주 바뀌지 않는 데이터는 적절한 기간 동안 캐시하면 외부 API 의존도와 호출 비용을 줄일 수 있습니다. 최신 요청이 실패했을 때 마지막으로 성공한 데이터를 임시로 제공하는 방식도 고려할 수 있습니다.

다만 오래된 데이터가 잘못된 결정을 만들 수 있는 서비스라면 캐시 시점과 갱신 실패 상태를 명확하게 표시해야 합니다.

운영 중 확인할 지표

• API별 성공률과 응답 시간
• 상태 코드별 오류 발생 횟수
• 재시도 후 복구된 요청 비율
• 호출 제한에 도달한 횟수
• 제공자별 월간 호출량과 비용

이 지표를 지속적으로 확인하면 사용자에게 장애가 크게 드러나기 전에 문제를 발견하고 대응할 수 있습니다.