Rate limit 에러에 직면했을 때 대응하는 방법

API를 다루다 보면 rate limit 에러는 피할 수 없는 문제다. 검색해서 이 글에 온 사람이라면 아마도 지금 이 에러가 발생하고 있을 것 같은데, 핵심은 문제를 크게 잡지 않는 것이다.

먼저 확인할 것들

문제가 터졌을 때 가장 먼저 해야 할 일은 상황을 좁혀가는 것이다.

• 로컬과 운영 중 어디에서 발생하는가?
• 같은 요청을 반복했을 때 일정하게 발생하는가?
• 에러 응답의 정확한 메시지는 무엇인가?
• 어느 엔드포인트에서 발생하는가?

이 네 가지를 먼저 적어두면 원인 후보가 확 줄어든다. 특히 로컬에서는 되는데 운영에서만 안 되는 경우라면 환경 설정 차이를 의심해야 한다.

응답과 로그를 함께 봐야 한다

curl -i 'https://api.example.com/endpoint' -H 'Authorization: Bearer token'

이 명령어로 응답 헤더와 상태 코드를 직접 확인하는 게 가장 빠르다. 응답 헤더에는 X-RateLimit-Remaining, Retry-After 같은 정보가 들어있는데, 이게 0에 가까우면 설정을 확인해야 한다.

동시에 서버 로그도 봐야 한다. 로그에 실제 요청 시간과 개수가 남아있으면, 의도한 것보다 많은 요청이 가는지 아니면 설정값이 너무 낮은지 판단할 수 있다.

로컬과 운영 환경 비교

대부분의 rate limit 문제는 환경 차이에서 온다. 확인해야 할 것들:

• API 키가 다른 등급인가?
• 요청을 보내는 IP가 다른가? (프록시, CDN 등)
• 배치 작업이 운영에서만 도는가?
• 타임아웃 설정이 다른가? (로컬에서는 재시도가 적고 운영에서는 많을 수 있음)

이런 것들을 체크리스트로 만들어두면 나중에 같은 문제가 생겼을 때 훨씬 빠르게 처리할 수 있다.

안전하게 수정하는 방법

한 번에 여러 설정을 바꾸지 마라. 가능하면:

1. 먼저 요청 간격을 늘려본다 (가장 무해함)
2. 그 다음 요청을 배치로 묶거나 캐싱을 추가한다
3. 마지막으로 API 키 등급을 올리거나 화이트리스트를 신청한다

각 단계마다 실제로 로그와 응답을 확인해서 문제가 해결됐는지 검증하는 게 중요하다.

결국 rate limit 문제는 급해서 막무가내로 수정했다가 사이드이펙트가 생기는 경우가 많다. 작은 확인을 차근차근 남기면서 진행하면 대부분 금방 해결된다.