레이트 리밋(RPM·TPM) 표기, 이렇게 읽으면 429가 덜 무섭습니다

API를 조금만 써 보면 429(Too Many Requests)를 만나게 됩니다. 이때 보는 숫자가 레이트 리밋인데, 표기가 제공사마다 달라 헷갈리기 쉽습니다. 널리 쓰이는 약어부터 정리하면 RPM은 분당 요청 수, TPM은 분당 토큰 수, RPD·TPD는 같은 걸 하루 단위로 센 값입니다. 여기에 동시 요청 수나 배치 큐 적재량 한도를 따로 두는 곳도 있습니다. 중요한 건 "요청 수"와 "토큰 수"가 별개 상한이라는 점입니다. 요청을 아주 적게 보내도 한 번에 긴 문서를 넣으면 TPM에서 먼저 막힙니다. 반대로 짧은 요청을 잘게 쪼개 보내면 RPM이 먼저 걸립니다. 어느 쪽에 걸렸는지는 보통 응답 헤더나 에러 메시지에 적혀 나오므로, 무작정 재시도하기 전에 메시지 본문을 먼저 읽는 편이 빠릅니다. TPM 계산 방식도 확인할 부분입니다. 입력 토큰만 세는지, 출력까지 합치는지, 요청에 적어 둔 최대 출력 토큰 값을 미리 예약분으로 차감하는지가 제공사·모델마다 다릅니다. 예약 방식이라면 최대 출력값을 필요 이상으로 크게 잡아 둔 것만으로도 한도가 빨리 소진될 수 있습니다. 스트리밍이라고 따로 깎아 주지는 않는 게 일반적입니다. 한도가 어느 단위로 묶이는지도 봐야 합니다. 보통 API 키 하나가 아니라 조직·프로젝트 단위로 합산되고, 모델별로 별도 한도가 걸립니다. 그래서 같은 조직의 다른 서비스가 쓰는 양까지 내 호출에 영향을 줍니다. 사용량 등급에 따라 한도가 올라가는 구조도 흔한데, 승급 조건과 반영 시점은 문서 기준으로 확인해야 합니다. 429를 만났을 때의 권장 대응은 대체로 비슷합니다. 재시도 간격을 점점 늘리는 지수 백오프를 쓰고, Retry-After 같은 헤더가 오면 그 값을 우선 따르고, 재시도 횟수에 상한을 둡니다. 실패하자마자 즉시 같은 요청을 던지는 루프는 한도를 더 밀어내기만 합니다. 여기 적은 약어와 동작 방식은 널리 쓰이는 공통 패턴이고, 구체적인 수치와 집계 규칙은 제공사 공식 문서·콘솔 기준이며 공지 없이 바뀌기도 합니다. 확인 체크리스트 - 내가 걸린 게 RPM인지 TPM인지 에러 메시지에서 먼저 확인 - TPM에 출력 토큰·최대 출력 예약분이 포함되는지 문서에서 확인 - 한도가 키 단위인지 조직·프로젝트 단위인지 확인 - 모델별로 한도가 따로 걸려 있는지 확인 - 재시도에 지수 백오프와 횟수 상한을 넣었는지 확인 - 수치는 반드시 사용 중인 제공사 콘솔의 현재 값으로 재확인