텔레그램 flood control, Retry-After를 받는 곳이 없었다

RetryAfter: Flood control exceeded. Retry in 3 seconds

2026년 8월 말에 받은 예외다. 텔레그램은 3초 뒤에 다시 오라고 알려 줬는데, 코드 어디에도 그 말을 듣는 곳이 없었다.

커뮤니티용 텔레그램 봇을 python-telegram-bot(이하 PTB)으로 운영하고 있다. 그날 아침 봇의 전달 기능이 한 방에 6초 동안 22건을 보냈다. 사진 앨범 두 묶음이 포함된 숫자다. 바로 뒤에 다른 기능이 같은 방으로 결과물을 올리려 했다. 만드는 데 시간이 걸리는 긴 텍스트였고 생성은 이미 끝나 있었다. 남은 일은 메시지를 보내는 것뿐이었는데 거기서 위 예외가 났다.

방에는 처리 중 오류가 났다는 안내 문구만 남았다. 이 작업은 원장에 기록해 두고 처리하는 종류였는데, 실패 처리 경로가 원장 항목까지 지웠다. 나중에 다시 집어 갈 주체가 없었고 완성된 결과물은 어디에도 전달되지 않았다. 3초 자고 다시 보냈으면 끝났을 일이다.

limiter 자리에 기록 훅이 앉아 있었다

텔레그램 Bot API는 짧은 시간에 요청이 몰리면 429로 거절하면서 몇 초 뒤에 다시 시도하라는 값(retry_after)을 함께 준다. PTB는 이것을 telegram.error.RetryAfter 예외로 올리고, 기다릴 시간은 예외 객체의 retry_after에 초 단위로 들어 있다(PTB 22.2부터는 PTB_TIMEDELTA 환경 변수를 켜면 timedelta로 온다). 텔레그램 봇 FAQ가 안내하는 그룹 한도는 분당 20건이라, 한 그룹에 6초 동안 22건이면 걸려도 이상하지 않은 양이다.

걸린 것보다 아무도 받지 않은 쪽이 문제였다. 코드 전체에서 RetryAfter를 찾아봤더니 받는 곳이 한 군데도 없었다.

보통은 이럴 일이 없다. PTB에는 rate limiter를 꽂는 자리가 있고, 여기에 꽂힌 객체의 process_request가 getUpdates를 뺀 모든 Bot API 호출을 감싼다. PTB가 제공하는 AIORateLimiter를 꽂으면 호출 간격을 조절해 주고, max_retries를 주면 RetryAfter가 왔을 때 기다렸다가 다시 시도한다. 기본값 0에서는 재시도하지 않는다.

이 자리는 하나뿐인데, 내 봇에서는 이미 다른 용도로 쓰고 있었다. 봇이 보낸 메시지의 id를 적어 두는 훅이다. 봇이 보내는 모든 메시지를 한 곳에서 잡을 수 있는 공통 지점이 여기밖에 없어서 빌려 썼다. 고치기 전의 모습이다.

class RecorderLimiter(BaseRateLimiter):
    async def process_request(self, callback, args, kwargs, endpoint, data, rate_limit_args):
        result = await callback(*args, **kwargs)
        ...  # 봇이 보낸 메시지 id 기록
        return result

이름은 limiter지만 속도 제한은 하지 않고 호출을 그대로 통과시킨다. 기록 용도로는 잘 동작했다. 다만 이 자리를 차지하면서, 원래 여기 들어갈 구현이 해 주던 flood control 대응이 봇 전체에서 통째로 빠졌다. 훅을 빌려 쓸 때는 그 점을 따져 보지 않았다.

같은 자리에서 재시도까지 받는다

모든 Bot API 호출이 지나는 공통 지점이 이 훅 하나이므로 재시도도 여기에 넣었다. 호출부마다 try/except를 달 필요가 없고, 한 곳만 고치면 봇의 모든 발송 기능이 한꺼번에 덮인다.

_RETRY_MAX = 3      # 첫 시도 뒤 최대 3번 더
_RETRY_CAP = 30.0   # 이보다 오래 기다리라면 포기
_RETRY_PAD = 0.5    # 텔레그램이 준 시간보다 조금 더

class RecorderLimiter(BaseRateLimiter):
    @staticmethod
    async def _call(callback, args, kwargs, endpoint):
        for attempt in range(1, _RETRY_MAX + 2):
            try:
                return await callback(*args, **kwargs)
            except RetryAfter as exc:
                delay = float(exc.retry_after) + _RETRY_PAD
                if attempt > _RETRY_MAX or delay > _RETRY_CAP:
                    raise
                await asyncio.sleep(delay)

process_request는 callback을 직접 부르는 대신 _call을 거치고, 그 뒤에 원래 하던 기록을 그대로 한다. 재시도할 때는 어느 엔드포인트가 몇 초 뒤 몇 번째로 다시 가는지 경고 로그를 남긴다.

텔레그램이 기다릴 시간을 알려 주므로 백오프 공식은 따로 만들지 않았다. 알려 준 값에 0.5초를 더해서 잔다. 정확히 그 시간만 자면 경계에서 한 번 더 걸릴 수 있어서 붙인 여유다.

재시도 세 번을 다 쓰면 마지막 예외를 그대로 올린다. 여기서 예외를 삼키면 호출부는 보냈다고 착각한다. 실패가 실패로 전달돼야 호출부가 기록을 남기든 사람에게 알리든 할 수 있다.

30초 넘게 기다리라고 하면 자지 않고 즉시 올린다. 이 훅은 모든 발송이 지나는 길목이라 여기서 오래 붙잡고 있으면 뒤에 줄 선 발송이 통째로 밀린다. 그만큼 기다리라는 응답은 잠깐 몰린 정도를 넘어 사람이 알아야 할 상태라고 봤다.

RetryAfter가 아닌 예외는 손대지 않는다. 채팅을 못 찾았다는 400을 세 번 다시 보내 봐야 결과는 같다.

테스트에서는 실제로 자지 않는다. asyncio.sleep을 잔 시간만 적어 두는 가짜 시계로 바꿔서 경계를 확인했다.

class Clock:
    def __init__(self):
        self.slept = []

    async def sleep(self, delay):
        self.slept.append(delay)

테스트 시작에서 asyncio.sleep을 이 객체의 sleep으로 바꾸고 finally에서 원래 함수로 되돌린다. 콜백은 앞의 몇 번은 예외를 던지고 그다음에 성공하는 가짜를 쓴다. 고정한 경계는 여섯 가지다.

  1. 한 번 걸려도 재시도해서 성공하면 그 결과를 돌려준다.
  2. 잔 시간이 텔레그램이 말한 값 이상이다. 3초를 받았으면 3.5초를 잔 것으로 기록된다.
  3. 계속 걸리면 첫 시도와 재시도 세 번, 합쳐 네 번만 호출하고 마지막 예외를 올린다. 잔 횟수는 세 번이다.
  4. 너무 긴 대기를 요구받으면 한 번도 자지 않고, 한 번만 호출한 채로 바로 올린다.
  5. RetryAfter가 아닌 예외는 재시도 없이 그대로 올린다.
  6. 재시도 끝에 성공한 메시지도 원래 하던 id 기록에 남는다.

여섯 번째는 이 훅이 두 가지 일을 하게 돼서 넣었다. 재시도를 끼워 넣다가 원래 하던 기록이 빠지면, 그 기록에 기대는 다른 기능이 조용히 망가진다.

이번에 안 고친 것

AIORateLimiter로 갈아타는 방법도 검토했다. 그쪽은 걸린 뒤에 기다려 줄 뿐 아니라 걸리기 전에 호출 간격도 조절해 준다. 하지만 자리가 하나라서, 바꾸려면 지금 그 자리에 있는 기록 훅을 어디로 옮길지부터 풀어야 한다. 이번에는 보류하고 재시도만 넣었다.

그래서 지금도 미리 속도를 줄이지는 않는다. 몰리면 여전히 한 번은 거절당하고, 그 뒤에 자고 다시 간다. 이번 증상을 없애는 데는 그것으로 충분했다.

실패 경로가 원장 항목을 지우는 부분도 건드리지 않았다. 전송 오류 한 번에 이미 계산이 끝난 결과물을 버리는 구조는 따로 봐야 할 문제로 남아 있다.