API Rate Limit 응답 형식이 일관성 없을 때 확인 순서

API에 rate limit을 적용하면 제한을 초과했을 때 특정 상태 코드와 메시지를 반환해야 한다. 그런데 같은 조건에서도 응답이 달라질 때가 있다. 이럴 때는 상태 코드부터 확인하는 게 핵심이다.

실제 요청으로 응답 확인하기

Rate limit을 테스트하려면 직접 API에 여러 번 요청을 보내본다.

curl -i 'https://example.com/api/items?page=1'
curl -i 'https://example.com/api/items?page=2'
curl -i 'https://example.com/api/items?page=3'

각 응답의 상태 코드와 헤더를 확인한다. 특히 X-RateLimit-* 헤더가 일관되게 나오는지 본다.

Rate Limit 헤더 확인

표준 rate limit 헤더는 다음과 같다:

• X-RateLimit-Limit: 시간당 최대 요청 수
• X-RateLimit-Remaining: 남은 요청 수
• X-RateLimit-Reset: 제한 초기화 시간

이 헤더들이 모든 응답에서 나오는지, 값이 일관된지 확인한다.

상태 코드 일관성 확인

Rate limit에 도달했을 때 항상 같은 상태 코드(보통 429)를 반환하는지 확인한다. 어떤 요청은 429를 반환하고 어떤 건 503을 반환하면 클라이언트가 헷갈린다.

# 짧은 간격으로 여러 요청을 보내기
for i in {1..20}; do
  curl -i 'https://example.com/api/items' 2>/dev/null | grep HTTP
  sleep 0.1
done

응답 본문 형식 확인

Rate limit 에러 응답의 JSON 형식도 일관되어야 한다. 어떤 때는 { error: "rate limited" }이고 어떤 때는 { message: "Too many requests" }면 클라이언트 처리가 복잡해진다.

로컬과 운영 환경 비교

로컬 개발 환경에서 한 번 확인하고, 운영 서버에서 한 번 더 확인해본다. 미들웨어나 프록시에서 다르게 처리할 수 있다.

결과 기록

Rate limit이 제대로 작동하는지 확인한 값들(상태 코드, 헤더, 응답 형식)을 정리해두면 배포 후 검증이 훨씬 빨라진다.