HTTP 429가 보일 때: Retry-After를 읽고 요청 간격 정하기

외부 API를 호출하는 프로그램에서 HTTP 429 응답을 받았다면 요청 속도 제한을 확인할 시점입니다. 이 글은 문서에 나온 상태 코드의 의미를 바탕으로 작은 호출 프로그램이 다음 요청 시간을 정하는 방법을 설명합니다. 특정 서비스의 실제 제한값을 측정한 결과는 아닙니다.

1. 먼저 응답을 기록합니다
기록할 항목은 요청 경로, 응답 시각, 상태 코드, Retry-After 헤더 유무입니다. 인증 값이나 개인 정보는 로그에 넣지 않습니다. 같은 기능의 버튼을 여러 번 눌렀는지, 반복 작업이 짧은 간격으로 실행됐는지도 확인합니다. 429는 일정 시간 동안 요청이 허용 범위를 넘었다는 뜻이며 제한 범위는 서비스마다 다를 수 있습니다.

2. Retry-After에는 두 표현이 있습니다
서버는 대기할 초 수나 다시 시도할 수 있는 날짜를 넣을 수 있습니다. 예를 들어 Retry-After: 30이면 응답을 받은 뒤 30초를 기다리는 뜻입니다. 날짜 형식이라면 현재 시각과 비교해 남은 시간을 계산합니다. 헤더가 없는 경우에는 서비스 문서를 확인하고 프로그램이 정한 대기 간격을 사용합니다. 여러 작업이 동시에 재개되지 않도록 작은 무작위 간격을 더하는 방식도 있습니다.

3. 재시도 대상과 횟수를 정합니다
조회 요청과 저장 요청은 처리 결과를 확인하는 방식이 다릅니다. 저장 요청은 응답을 받지 못해도 서버가 이미 처리했을 가능성을 고려해야 합니다. 요청 식별자나 조회 화면으로 상태를 확인한 뒤 다시 보내세요. 재시도 횟수에 상한을 두고 그 횟수에 도달하면 현재 상태와 수동 확인 방법을 사용자에게 안내합니다.

4. 가상의 실행 흐름을 살펴봅니다
10:00:00에 요청을 보냈고 429와 Retry-After: 30을 받았다고 가정합니다. 프로그램은 10:00:30 이후로 다음 요청을 예약합니다. 그동안 같은 작업에서 중복 요청을 만들지 않고 “잠시 후 다시 확인” 상태를 보여 줍니다. 그림은 요청→429 확인→대기 시간 계산→처리 상태 확인→재시도의 순서입니다. 시각과 수치는 설명용 예시입니다.

5. 서비스 규칙과 함께 봅니다
MDN은 429가 요청 과다를 뜻하며 Retry-After가 포함될 수 있다고 설명합니다. 헤더 값은 초 수 또는 HTTP 날짜 형식입니다. 실제 서비스가 제공하는 제한 정책과 응답 헤더를 우선 확인하세요. 공식 참고: MDN ‘429 Too Many Requests’ https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429 및 ‘Retry-After’ https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After (확인일 2026-09-23). 그림과 시간표는 직접 구성했습니다.

바로 해볼 연습
테스트 응답에 Retry-After: 45가 있고 응답을 받은 시각이 14:20:00이라고 가정해 보세요. 다음 요청은 14:20:45 이후로 잡습니다. 헤더가 날짜 형식인 경우에는 그 날짜를 시각으로 해석해 남은 시간을 계산합니다. 두 방식 모두 현재 시계가 맞는지 확인하고, 대기 중 화면에 어떤 안내를 보여 줄지도 함께 적어 보세요.

429 응답 한 건을 읽는 순서

가상 호출 기록을 “14:20:00 요청, 응답 429, Retry-After: 45”로 둡니다. 이때 가장 빠른 다음 요청 시각은 14:20:45입니다. 응답 본문이나 서비스 문서가 별도 한도를 안내한다면 그것도 함께 봅니다. 기록에는 요청 경로, 응답 시각, 상태 코드, 헤더 값, 다음 요청 예정 시각을 남기고 인증 값은 제외합니다. 실제 한도나 대기 시간은 서비스가 보내는 응답과 정책을 기준으로 정하세요.

응답에서 본 값	읽는 방법	다음 행동
Retry-After: 45	응답 수신 뒤 45초	14:20:45 이후 재확인
HTTP 날짜	지정된 시각 이후	현재 시각과 차이를 계산
헤더 없음	서버가 대기값을 제시하지 않음	서비스 문서와 앱 정책 확인
여러 작업의 동시 재개	같은 순간 요청이 몰릴 수 있음	정책 범위에서 간격을 분산

표의 45초는 계산 예시이며 특정 API의 허용값이 아닙니다. HTTP 날짜 값은 시간대가 포함된 형식으로 해석합니다. 기기 시계가 다르면 계산한 대기 시간도 달라질 수 있으므로 시계 상태를 확인하고 서버가 제공하는 다른 제한 헤더나 문서를 함께 살펴봅니다.

두 형식을 읽는 작은 JavaScript 함수

function retryAfterMs(value, now = Date.now()) {
  if (typeof value !== 'string') return null;
  const text = value.trim();
  if (/^[0-9]+$/.test(text)) return Number(text) * 1000;
  const target = Date.parse(text);
  return Number.isNaN(target) ? null : Math.max(0, target - now);
}
// retryAfterMs('45', Date.parse('2026-09-23T05:20:00Z')) → 45000

이 함수는 헤더를 밀리초로 바꾸는 설명용 예시입니다. 반환값 null은 헤더가 없거나 해석할 수 없는 경우이므로 호출자가 서비스별 기본 정책을 선택해야 합니다. 실제 프로그램에는 지나치게 큰 값의 처리, 최대 재시도 횟수, 취소, 요청 중복 방지, 기록을 추가하세요. 시간 계산만으로 요청을 자동 재전송하면 저장 결과를 확인하지 못한 경우가 남습니다.

조회와 저장을 구분하는 재시도 표

요청	429 뒤 확인	재시도 전 점검
목록 조회	대기값과 요청 간격	같은 화면에서 중복 조회가 쌓였는지
신청 저장	접수 상태와 요청 식별자	이미 저장된 항목이 있는지
파일 업로드	업로드 결과와 파일 식별자	완료된 파일이 다시 올라가지 않는지

저장 요청은 네트워크 응답을 못 받았어도 서버에서 처리가 끝났을 수 있습니다. 조회 화면이나 요청 식별자로 결과를 확인하고 재전송 여부를 결정하세요. 서버가 중복 방지 키를 지원하는 경우에는 그 정책을 따라 같은 작업을 구분할 수 있습니다. 지원 여부가 확인되지 않았다면 기능이 있다고 가정하지 않습니다.

화면 안내와 종료 조건

요청이 잠시 대기 중입니다. 다음 확인 시각은 14:20:45 이후입니다. 현재 처리 상태를 확인할 수 있으며, 같은 저장 작업을 다시 누르기 전에 접수 목록을 살펴보세요.

재시도에는 상한을 둡니다. 예를 들어 연습용으로 최대 3회라고 정했다면 세 번째 뒤에도 결과가 확인되지 않을 때는 현재 요청 시각과 상태, 사용자가 직접 확인할 화면을 보여 줍니다. 3회는 서비스 권장값이 아니라 제품에서 정해야 하는 예시입니다. 화면의 남은 시간은 실제로 계산한 값과 맞아야 합니다.

Q. 429가 나오면 곧바로 같은 요청을 다시 보내나요? Retry-After와 서비스 정책을 읽고 다음 시각을 정합니다.

Q. Retry-After가 없으면 어떻게 하나요? 서비스 문서와 앱의 대기·상한 정책을 사용하고 그 근거를 기록합니다.

Q. 저장 화면에서 응답을 못 받았어요. 재전송 전에 서버가 이미 처리했는지 조회 경로로 확인합니다.

공식 참고: MDN 429 상태, MDN Retry-After(2026-09-23 확인). 관련 글: 저장 버튼 중복 입력 다루기, 대기·완료·재확인 화면 설계.