여러 구독 계정에 요청을 나눠 보내는 라우터를 운영한다면, "모든 계정이 소진됐다"는 거절이 오래된 사용량 숫자 때문에 나갈 수 있다는 점을 의심해 볼 만하다. 내 개인 라우터는 2026-11-04 오후에 두 번, 모든 Claude 요청을 "모든 계정의 사용률이 95% 이상이라 잠시 제외되었습니다"라는 메시지로 거절했다. 재설정 시각은 몇 시간 뒤로 찍혀 있었다. 그런데 바로 사용량을 새로 고치자 한 계정은 98%, 다른 시점에는 93%가 남아 있었다. 고친 방법은 이렇다. 사용량 때문에 모든 후보가 빠질 때만, 5분보다 오래된 계정의 사용량을 한 번 다시 읽고 선택을 한 번 더 돌린다. 이 글은 그 수정의 설계와 리뷰가 잡은 두 가지 결함, 남은 한계를 다룬다. 이 글은 작성자의 작업 기록을 바탕으로 Claude 모델이 초안을 작성했다.

거절은 났는데 사용량은 남아 있었다

이 라우터는 같은 제공자의 구독 계정 여러 개를 등록해 두고, 요청이 올 때마다 사용량과 쿨다운을 보고 보낼 계정을 고른다. 사용률이 높은 계정은 잠시 후보에서 뺀다. 사용량 숫자는 스케줄러와 수동 명령, 요청 경로의 갱신 기능이 주기적으로 받아 와 저장해 둔다. 선택 단계는 저장된 값을 읽기만 한다.

이슈에 남긴 기록은 다음과 같다.

  • 2026-11-04 15:53 KST와 19:17 KST, 두 번 모든 Claude 요청이 사용량 소진 메시지로 거절됐다.
  • 거절 응답의 재설정 시각은 몇 시간 뒤였다.
  • 곧바로 router usage refresh를 실행하자 한 계정의 남은 사용량이 첫 번째에는 98%, 두 번째에는 93%로 나왔다.

그러니까 선택 단계가 본 숫자와 실제 계정 상태가 달랐다. 저장된 사용량이 오래돼 있었고, 거절 경로는 그 숫자를 다시 확인하지 않았다. 사람이라면 "정말 다 썼나?" 하고 한 번 더 볼 상황인데, 라우터는 오래된 숫자만 믿고 끝냈다. 이것이 이번 수정이 겨냥한 오탐이다.

모든 계정을 빼야 하는 순간이 오면, 그 판단의 근거가 된 숫자가 얼마나 오래됐는지부터 확인해야 한다. 거절은 되돌리기 어렵고, 다시 읽기는 싸다.

429와 529를 먼저 구분했다

이슈 제목에는 "429"라고 적었다. 그런데 설계 단계에서 코드의 실제 응답 규칙을 확인해 보니 상태 코드가 두 갈래였다.

라우터가 소진 상황에 돌려주는 응답
상황상태 코드본문과 헤더
쿨다운 재설정 시각을 알고 있음429rate_limit_error와 Retry-After
재설정 시각을 모름(사용량 소진)529overloaded_error, 소진 문구와 재설정 시각

RFC 6585는 429를 "the user has sent too many requests in a given amount of time"인 경우로 정의하고, 기다릴 시간을 Retry-After로 알려 줄 수 있다고 적는다. 라우터가 429를 알려진 쿨다운에만 쓰는 것은 이 정의와 맞는다. 재설정 시각을 모르는 소진은 529로 나간다. 이슈에 "429"라고 적은 응답이 실제로 어느 코드였는지는 기록에 남지 않았다. 설계 노트에는 "계획의 429는 라우터의 소진 응답을 뜻한다"는 주석을 따로 달았다. 수정은 두 응답 규칙을 그대로 두고, 그 응답을 내기 전 단계만 바꾸기로 했다.

이 구분은 나중에 테스트 리뷰에서 다시 중요해졌다. 그 이야기는 아래에서 이어진다.

언제 다시 읽을지 정한 규칙

설계 노트는 필요한 기능을 다섯 개로 셌다.

  1. 사용량 때문에 모든 선택 후보가 빠지는지 판단한다.
  2. 오래된 계정의 사용량을 다시 읽는다. 시도 간격은 5분이고, 계정마다 한 번에 하나만 실행한다.
  3. 새로 읽기에 성공한 값으로 선택을 한 번 다시 돌린다. 실패하면 원래 값을 유지한다.
  4. 다시 읽은 결과를 라우팅 기록의 사유에 남긴다.
  5. Codex와 Claude 게이트웨이 요청 모두에서 시간, 실패, 동시성을 테스트한다.

판단은 순수 함수 하나가 맡는다. 계정 목록과 현재 시각, 저장된 사용량 상태, 설정을 받아 다시 읽을 계정 ID 목록을 돌려준다. 여전히 선택 가능한 후보가 하나라도 있으면 빈 목록이다. 사용량 때문에 빠진 계정이 없어도 빈 목록이다. 그 밖의 경우에는 사용량으로 빠졌고, 주기 조회 대상이며, 마지막 확인이 300,000 ms보다 오래된 구독 계정만 돌려준다.

아래 흐름도는 요청 하나가 거절되기 전에 지나가는 판단 순서를 보여 준다.

요청 하나가 거절되기 전에 지나가는 다섯 단계를 순서대로 보여 주는 흐름도다. 먼저 사용량 때문에 모든 선택 후보가 빠지는지 판단하고, 모두 빠졌다면 마지막 확인이 5분보다 오래된 계정을 고른다. 이어서 계정마다 한 번에 하나만 실행되도록 사용량을 다시 읽고, 새로 읽은 값으로 선택을 한 번 다시 돌린다. 다시 읽기에 실패하면 원래 값을 유지한다. 마지막으로 다시 읽은 결과를 logs/routing.jsonl 라우팅 기록에 사유로 남긴다. 사용량을 다시 읽는 단계가 강조되어 있다.
오래된 사용량만 보고 모든 계정을 거절하던 오탐은 거절하기 직전에 오래된 계정만 한 번 다시 읽고 선택을 다시 돌려서 막는다는 것이 이 수정의 핵심이다.

각 수치와 선택의 이유는 이렇다.

  • 신선도 경계 5분. 기존 선택 로직의 오래됨 한도는 10분이다. 이보다 짧게 잡아, 거절 직전에는 더 엄격하게 본다. 5분 안에 확인한 값은 틀렸더라도 다시 읽지 않는다. "틀렸지만 신선한 값"은 범위 밖으로 명시했다.
  • 단일 실행. 같은 계정에 대해 이미 갱신이 돌고 있으면 새로 시작하지 않고 그 결과를 기다린다. 기존 스케줄러, 수동, 요청 경로 갱신과 시도 기록을 공유한다.
  • 대기 상한 25초. 계정별 기존 실행 한도를 그대로 썼다. 요청 경로용 타임아웃 상수를 새로 만들지 않기 위해서다. 더 짧게 잡으면 지연은 줄지만, 쓸모 있는 조회가 끝나기 전에 거절할 수 있다.
  • 실패 시 원래 값 유지. 조회 오류, 시간 초과, 자격 증명 없음은 모두 라우팅에 쓰는 값을 건드리지 않는다. 원래의 소진 메시지와 재설정 시각이 그대로 나간다.

단일 실행은 Go의 singleflight 패키지가 설명하는 방식과 같은 생각이다. 그 문서는 같은 키의 실행이 "only one execution is in-flight for a given key at a time"이 되도록 하고, 중복 호출자는 원래 실행이 끝나기를 기다려 같은 결과를 받는다고 설명한다. 라우터는 이 패키지를 쓰지 않는다. Rust로 된 기존 갱신 장치에 같은 성질을 넣은 것이다. 두 요청이 겹쳐도 조회는 한 번만 시작되는지 확인하는 테스트도 계획 검증의 권고에 따라 넣었다.

기록 사유는 세 가지로 정했다. 새 값을 저장했고 라우팅에 성공하면 usage_refresh:freed, 새 값을 저장했는데도 보낼 계정이 없으면 usage_refresh:still_excluded, 시도가 실패하면 usage_refresh:failed다. 다시 읽기를 시도하지 않은 요청에는 사유를 붙이지 않는다. 이 값은 CLI 로그와 logs/routing.jsonl로 이어진다. 다음에 같은 거절이 나면 "다시 읽었는데도 소진"인지 "다시 읽기가 실패"인지 로그에서 바로 구분할 수 있다.

버린 대안도 있다. 네트워크 조회를 선택 로직의 핵심 크레이트 안으로 옮기는 안이다. 순수한 선택 코드가 I/O에 묶이고 호출자가 더 많이 영향을 받기 때문에, 허브 수준에서 사전 점검을 한 번 하고 정상 선택을 한 번 돌리는 쪽을 골랐다.

리뷰가 잡은 두 가지 결함

이 슬라이스는 GPT 쪽 에이전트가 테스트와 로직을 썼고, Claude 쪽 리뷰어가 각각 한 번씩 검토했다. 두 리뷰 모두 처음에는 실패했다.

테스트: 429와 529를 모두 받아 준 단언

테스트의 공통 도우미 assert_exhausted는 다음과 같았다.

assert!(matches!(sent.status, 429 | 529), ...)

리뷰는 assertions 5점을 주고 반례를 들었다. 이번 소진 사례들은 모두 재설정 시각을 모르는 경우라 정답은 529다. 그런데 로직이 실수로 429를 돌려줘도 이 도우미를 쓰는 다섯 테스트가 그대로 통과한다. 위에서 정리한 두 응답 규칙을 테스트가 지키지 못한 셈이다. 정정은 한 번으로 끝났다. 상태 코드를 정확히 529로 단언하고, 본문에 overloaded_error가 들어 있는지도 확인하게 했다.

로직: 소진 검사를 하지 않는 정책에서도 다시 읽었다

로직 리뷰는 correctness 6, integration 6으로 실패했다. 반례 입력은 이랬다. 선택 정책이 가장 오래전에 쓴 계정을 고르는 LeastRecentlyUsed이고, 모든 계정이 사용량으로 제외된 상태로 저장돼 있으며, 마지막 확인은 300,000 ms보다 오래됐다.

이 정책은 원래 선택 단계에서 사용량 검사를 건너뛴다. 그러니 후보는 이미 선택 가능하고, 다시 읽을 이유가 없다. 그런데 판단 함수는 정책을 보지 않고 "모두 제외"로 판정했다. 이 반례에서는 요청이 최대 25초짜리 강제 조회를 기다릴 수 있고, 기록에도 usage_refresh:* 사유가 붙는다. 계획 검증 때 받은 권고 중 하나가 "트리거를 실제 선택 가능 여부에 두라"였는데, 정책 차이까지는 반영하지 못했던 것이다.

정정은 정책 값을 판단 함수까지 전달하고, LeastRecentlyUsed면 빈 목록을 돌려주게 한 것이다. 이 경우를 확인하는 테스트도 하나 더했다. 두 리뷰의 지적은 각각 정정 커밋 한 번으로 처리했다.

두 리뷰의 지적과 정정
리뷰점수지적정정
테스트assertions 5소진 단언이 429와 529를 모두 허용정확히 529와 overloaded_error 단언
로직correctness 6, integration 6LeastRecentlyUsed 정책에서도 강제 조회정책을 전달해 해당 정책에서는 다시 읽지 않음, 테스트 1개 추가

검증 결과

테스트 먼저 커밋에서는 의도한 실패 8개를 확인했다. 로직을 넣은 뒤 이 기능의 테스트 파일은 9개 모두 통과했다. 실행 결과의 테스트 이름은 다음과 같다.

running 9 tests
test missing_credential_keeps_the_original_routing_snapshot ... ok
test refreshed_exhaustion_uses_the_new_reset ... ok
test claude_gateway_refreshes_cli_usage_before_routing ... ok
test stale_exclusion_refreshes_and_routes ... ok
test five_minute_freshness_and_attempt_gap ... ok
test eligible_account_prevents_refresh_of_excluded_account ... ok
test hung_refresh_returns_quota_at_25_seconds ... ok
test overlapping_requests_share_one_refresh ... ok
test failed_fetch_preserves_original_answer_and_usage ... ok

작업 공간 전체는 로컬에서 1,363개 통과, 0개 실패였다. 포맷 검사, clippy -D warnings, 파일당 400줄 검사, 비밀값 검사도 통과했다. CI의 첫 실행은 이 변경과 무관한 Windows 데스크톱 테스트 3개 때문에 실패했다. 같은 테스트가 다른 실행 세 번에서도 실패한 기록이 있어 불안정한 테스트로 분류하고 이슈를 따로 열었다. 재실행에서는 테스트가 통과했지만 이번에는 비밀값 검사가 실패했다. 원인은 이 PR이 아니었다. CI의 gitleaks가 기본값대로 모든 ref를 검사했고, 같은 저장소에서 진행 중이던 다른 작업 브랜치의 커밋 두 개에 generic-api-key 탐지 5건이 있었다. 나는 그 브랜치가 병합되기를 기다리는 쪽을 골랐다. 그 PR이 무시 목록 파일을 가지고 develop에 들어간 뒤 검사가 통과했다. 최종 검사는 develop을 두 번 따라잡은 뒤의 커밋에서 통과했고, PR을 develop에 병합했다.

과정에서 생긴 편차도 기록해 둔다. 리뷰 요청 묶음을 만드는 도구가 .rs 경로를 분류하지 못해, 로직 리뷰 요청은 도구 대신 직접 조립했다. 이 저장소의 CI에는 의도한 실패를 허용하는 단계가 없어서, 테스트 PR을 따로 열지 않고 테스트 먼저 커밋과 로직 커밋을 한 브랜치에 쌓아 PR 하나로 냈다.

GitHub의 Codex 리뷰 봇은 P2 지적 다섯 건을 남겼다. 한 건은 로직 정정 커밋에서 고쳤고, 나머지 네 건은 이슈로 열었다.

재시도 기준을 정한 다른 사례는 AI 영상 생성 파이프라인의 재시도 기준에 있다. 여러 계정을 다루다 자격 증명이 다른 계정에 귀속된 버그는 다계정 로그인 버그 기록에서 다뤘다. 다른 글은 프로그래밍 카테고리에서 볼 수 있다.

남은 한계

  • 배포하지 않았다. 수정은 develop에 병합됐지만 실행 중인 서비스를 다시 빌드하고 재시작하는 일은 사용자 승인을 기다린다. 실제 운영에서 같은 오탐이 사라졌는지는 아직 관찰하지 못했다.
  • 오탐 재현은 기록에 근거한다. 두 번의 거절과 새로 고친 사용량은 이슈 기록이다. 이 글을 쓰면서 다시 재현하지 않았다.
  • 이미지 요청 경로는 다루지 않는다. 그 경로는 선택 코어를 직접 불러 이번 사전 점검을 거치지 않는다.
  • 틀린 신선한 값은 남는다. 5분 안에 받은 값이 틀렸다면 경계를 넘을 때까지 그대로 쓴다.
  • 단일 실행은 프로세스 단위다. 스케줄러 없이 뜬 다른 프로세스와는 진행 중 실행이나 시도 기록을 공유하지 못한다.
  • 설계의 독립성이 약하다. 트리거 위치, 5분 경계, 사유 코드는 작업을 지휘한 쪽이 정했고, GPT 쪽 작성자가 설계 노트로 옮겨 적었다. 설계 노트가 작성자의 독자 판단이라고 보기는 어렵다.

이번 수정이 바꾼 것은 거절의 기준이 아니라 거절 직전의 확인 한 번이다. 설계대로라면 다시 읽기에 실패해도 이전과 같은 응답으로 거절하고, 달라지는 것은 최대 25초의 대기다. 운영에서 이 성질이 지켜지는지는 배포 뒤에 확인할 부분이다.

자주 묻는 질문

왜 매 요청마다 사용량을 새로 읽지 않나요?

조회는 외부 호출이라 지연을 늘립니다. 그래서 사용량 때문에 모든 후보가 빠지는 순간에만, 5분보다 오래된 계정만 다시 읽도록 범위를 좁혔습니다.

다시 읽기가 실패하면 어떻게 되나요?

라우팅에 쓰는 값을 바꾸지 않고 원래의 소진 응답과 재설정 시각을 그대로 돌려줍니다. 기록에는 usage_refresh:failed 사유가 남습니다.

여러 요청이 동시에 오면 조회가 여러 번 일어나나요?

같은 계정에 대해서는 한 번만 시작합니다. 늦게 온 요청은 진행 중인 조회를 최대 25초까지 기다려 그 결과를 함께 씁니다. 겹치는 두 요청에 조회가 한 번만 일어나는지 테스트로 확인했습니다.

이 수정으로 운영 중 오탐이 사라졌나요?

아직 확인하지 못했습니다. 코드는 병합됐지만 실행 중인 서비스의 재빌드와 재시작은 사용자 승인을 기다리고 있습니다.

참고한 자료