API가 429를 반환할 때 클라이언트가 해야 할 일

API가 429 Too Many Requests를 반환하면 클라이언트는 무작정 즉시 다시 보내서는 안 됩니다. 서버가 부담을 줄이려고 제한했는데 재시도 폭풍을 만들면 장애가 길어집니다. 재시도 간격과 총 시도 횟수를 조절해야 합니다.

429의 범위를 파악한다

계정별 한도인지, IP별 한도인지, 특정 작업의 동시 실행 제한인지 확인합니다. 같은 제한을 공유하는 작업들이 각자 독립적으로 재시도하면 전체 요청량이 더 늘 수 있습니다.

Retry-After를 존중한다

서버가 재시도 가능 시각 또는 대기 초를 알려주면 그 값을 기준으로 기다립니다. 헤더가 없을 때는 지수 백오프와 무작위 지연을 사용해 모든 클라이언트가 동시에 다시 몰리지 않게 합니다.

재시도 예산을 둔다

최대 횟수와 전체 대기 시간을 정하고 마감 시각을 넘기는 작업은 실패로 처리하거나 큐에 보냅니다. 사용자 화면에는 진행 상태와 다음 시도 가능 시점을 알려야 합니다.

쓰기 요청의 중복을 방지한다

429 전에 서버가 일부 작업을 수행했을 가능성을 고려합니다. 주문·결제 같은 쓰기 요청은 멱등 키와 업무 고유키를 사용해 네트워크 오류와 재시도 중에도 중복 실행을 막습니다.

서버와 클라이언트 지표를 함께 본다

429 비율, 재시도 성공률, 평균 대기, 최종 실패를 봅니다. 한도를 늘리기 전에 쓸데없는 폴링이나 중복 요청이 없는지 줄이는 것이 우선일 수 있습니다.

현장에 적용할 때의 순서

1. 429 범위와 Retry-After 값 해석
2. 백오프·무작위 지연·재시도 예산 적용
3. 쓰기 요청에 멱등 키 추가

주의할 실패: 모든 클라이언트가 즉시 무한 재시도

관찰할 지표: 429 비율·재시도 성공률·최종 실패

적용 전 체크리스트

• Retry-After 파싱과 백오프를 구현한다
• 재시도 횟수·전체 대기 시간 상한을 둔다
• 쓰기 요청의 멱등 처리를 시험한다

참고 자료

RFC 6585 — Additional HTTP Status Codes, Section 4. 429 응답과 Retry-After 사용은 IETF RFC를 참고했습니다. 재시도 예산과 멱등 처리 방식은 클라이언트 운영 제안입니다.

이미지와 도식은 이해를 돕기 위한 개념 시각화입니다. 특정 고객의 실제 설비·데이터·화면을 재현한 것이 아닙니다.

#HTTP429 #RateLimit #RetryAfter #API운영 #재시도 #백오프 #멱등성 #트래픽제어 #웹개발 #장애대응