백오프를 걸어 둔 Sheets 호출이 5xx 한 번에 죽었다

(사전 동기화) → (대상 워크북 열기) → open_by_key
  → Spreadsheet.__init__ 의 메타데이터 조회
  → APIError [503]: The service is currently unavailable.

2026년 9월 초, 보고서를 만드는 명령이 “집계 중 오류가 발생했다”는 안내로 끝났을 때 로그에 남아 있던 경로다. 문구만 보면 집계 로직의 버그처럼 보이는데 집계는 시작도 하지 않았다. 워크북을 여는 첫 왕복에서 예외가 났다.

Google 쪽의 일시 장애다. 같은 명령을 사람이 다시 실행했을 때는 바로 통과했다.

이상한 건 이 예외가 사용자에게까지 올라왔다는 점이었다. 커뮤니티용 텔레그램 봇은 Google Sheets를 저장소로 쓰고, gspread로 시트를 읽고 쓴다. gspread에는 BackOffHTTPClient라는 HTTP 클라이언트가 들어 있고, 이걸 끼우면 429와 5xx 응답을 지수 백오프로 다시 시도한다. 봇의 시트 접근은 전부 공용 팩토리 함수 하나를 거쳐 클라이언트를 얻고, 그 팩토리가 이 백오프 클라이언트를 끼운다. 그래서 Google 쪽의 짧은 장애는 사용자 눈에 보이지 않을 것이라고 생각하고 있었다.

팩토리를 거치지 않는 호출이 하나 있었다

그 보고서를 만드는 함수 하나만 공용 팩토리를 쓰지 않고 gspread.service_account(...)를 직접 부르고 있었다. 직접 부르면 gspread의 기본 HTTP 클라이언트가 붙는다. 기본 클라이언트는 재시도하지 않는다.

저장소 전체에서 직접 호출을 찾아봤다. 봇 코드 안에서는 이 한 곳뿐이었고, 나머지는 손으로 한 번 돌리고 마는 일회성 스크립트들이었다. “봇의 시트 접근은 전부 백오프를 탄다”는 내 믿음은 한 군데만 빼고 사실이었는데, 그 한 군데가 사용자가 직접 부르는 명령의 맨 첫 왕복이었다.

직접 호출을 공용 경로로 바꿨다. 공용 경로는 스프레드시트 핸들을 스레드별로 재사용하기도 해서, 워크북을 여는 왕복도 한 번 줄었다.

11월 초, 팩토리를 거쳤는데도 502 한 번에 죽었다

시트에 저장하는 작업 한 건이었다. 이번 경로는 공용 팩토리를 제대로 거치고 있었다. 백오프 클라이언트가 끼워져 있는데 재시도 없이 바로 예외가 났다.

gspread의 APIError는 오류 응답 본문을 JSON으로 읽어 code를 채운다. Sheets API가 직접 내는 오류는 JSON이라 문제가 없다. 그런데 Google이 502를 JSON이 아니라 HTML 오류 페이지로 돌려주는 경우가 있다. 이때는 본문을 JSON으로 읽지 못하고 APIError.code가 -1이 된다.

BackOffHTTPClient의 재시도 판정은 이 code를 본다. 500 이상이면 서버 오류로 보고 다시 시도하는데, -1은 500 이상이 아니다. 실제 HTTP 상태는 502였지만 판정에 쓰인 숫자가 -1이어서 재시도 대상에서 빠졌고 예외가 그대로 올라왔다.

재시도 정책 자체는 맞았다. 정책에 들어가는 입력, 즉 오류를 분류하는 값이 응답 형식에 따라 달라지고 있었다. 내가 쓰는 gspread 버전에서 본 동작이고, 버전 번호는 커밋에 남기지 않아 여기에 적지 못한다.

-1일 때만 실제 상태 코드를 끼워 넣는다

예외 객체에는 원래 응답이 response로 달려 있고, 거기에는 진짜 HTTP 상태 코드가 있다. code가 -1일 때만 그 값으로 바꿔 끼운 뒤 예외를 다시 던지는 얇은 클라이언트를 만들었다.

class _HttpStatusFromResponse(gspread.http_client.HTTPClient):
    def request(self, *args, **kwargs):
        try:
            return super().request(*args, **kwargs)
        except gspread.exceptions.APIError as err:
            status = getattr(getattr(err, "response", None), "status_code", None)
            if err.code == -1 and isinstance(status, int):
                err.code = status
                err.error = {**err.error, "code": status}
            raise

class _BackOffClient(gspread.BackOffHTTPClient, _HttpStatusFromResponse):
    """MRO: BackOff.request → _HttpStatusFromResponse.request → HTTPClient.request."""

이 클라이언트는 놓이는 자리가 중요하다. 백오프 클라이언트 바깥에서 예외를 고치면 이미 늦다. 재시도 판정은 백오프 클라이언트의 request 안에서 일어난다. 그래서 다중 상속으로 순서를 잡았다. _BackOffClient의 MRO(메서드 탐색 순서)에서 BackOffHTTPClient 다음이 _HttpStatusFromResponse이므로, 백오프 쪽의 super().request()가 내 클래스를 먼저 거친다. 백오프가 예외를 받을 때는 code가 이미 502로 바뀌어 있다.

재시도 판정식 자체는 건드리지 않았다. 판정식을 고치려면 라이브러리의 재시도 로직을 복사해 내가 들고 있어야 한다. 틀린 것은 판정에 들어가는 값 하나였으므로 그 값만 바로잡았다.

팩토리는 한 줄만 바뀌었다.

def service_account():
    return gspread.service_account(
        filename=os.environ["SA_JSON_PATH"],
        http_client=_BackOffClient,   # 전에는 gspread.BackOffHTTPClient
    )

네트워크 없이 확인할 수 있게, 세션이 HTML 502를 한 번 주고 다음에 200을 주도록 흉내 낸 테스트를 붙였다.

def test_html_502_is_retried():
    client = _BackOffClient(auth=fake_credentials)
    calls = []
    seq = [_resp(502, "<html>Error 502</html>", "text/html"),
           _resp(200, '{"ok": true}', "application/json")]

    def fake_request(*a, **k):
        calls.append(1)
        return seq[len(calls) - 1]

    client.session = mock.Mock()
    client.session.request.side_effect = fake_request
    with mock.patch("time.sleep") as sl:
        r = client.request("get", "https://example/x")
    assert r.status_code == 200
    assert len(calls) == 2
    sl.assert_called_once()

time.sleep을 막아 두어 테스트가 백오프 대기 시간만큼 느려지지 않게 했고, 그 호출 횟수로 재시도가 정확히 한 번 일어났는지도 본다.

반대 방향 테스트도 하나 넣었다. HTML로 온 400은 code가 400으로 바뀌되 재시도는 하지 않아야 한다. 상태 코드를 바로잡는 수정이 “HTML 응답이면 무조건 재시도”로 번지지 않았는지 확인하는 용도다.