API 한도 폴백을 2단계로 설계하고 문서화하다

주간 API 한도 초과 시 자동으로 작동하는 폴백 메커니즘을 문서화했다. 단순한 실패 처리가 아니라, 모델 폴백(A)과 계정 로테이션(B) 두 겹으로 방어하는 구조를 명시하고, 팀이 이해하기 쉽도록 정리했다.

왜 폴백 메커니즘을 기록해야 했나

API 쿼터 시스템은 서비스 운영의 핵심 인프라다. 특히 주간 한도처럼 시간에 따라 리셋되는 제약 조건에서는, 한도에 도달했을 때 시스템이 우아하게 저하(graceful degradation)되는지가 생사를 갈린다. 그런데 우리 시스템의 폴백 전략은 코드에는 있었지만 누구도 이게 어떻게 작동하는지 명확히 설명한 문서가 없었다.

팀 리딩 관점에서, 이건 위험 신호다. 운영 중 뭔가 이상할 때 "어? 왜 이 요청은 다른 모델로 처리되지?" 또는 "어? 왜 다른 계정으로 전환됐지?"라고 물어볼 수 없으면, 문제 해결이 늦어진다. 또 신입이나 온보딩 중인 팀원이 시스템의 전체 흐름을 이해할 수 없다. 따라서 명시적인 문서화가 코드만큼 중요하다.

2층 방어 구조: A+B 폴백

폴백 전략을 두 단계로 구성했다.

이렇게 두 개의 방어선(defense-in-depth)을 둔 이유는:

• A만으로 부족할 수 있다. 모델 폴백은 빠르지만, 가벼운 모델도 쿼터가 제한되어 있다. 트래픽 스파이크가 심하거나 여러 서비스가 같은 한도를 공유할 때, A 단계만으로는 모두를 감당 못 한다.

• B는 최후의 보루다. 계정 로테이션은 독립적인 한도를 확보하지만, 여러 계정을 관리해야 하는 오버헤드가 있다. 그래서 먼저 A(빠른 폴백)를 시도하고, 그것도 부족할 때만 B로 간다.

• 가시성이 높아진다. 폴백이 발생한 상황(어느 단계인지, 왜인지)을 명확히 기록해두면, 나중에 "이 기간에 왜 응답이 느렸는가?" 또는 "계정 로테이션이 너무 자주 일어나나?" 같은 질문에 답할 수 있다.

문서화의 의미

코드 자체는 이미 작동 중이었다. 그런데 문서가 없으면 코드는 블랙박스가 된다. 팀원들이 시스템의 동작을 감으로만 이해하거나, 잘못 이해하거나, 나중에 같은 실수를 반복한다.

특히 우리 팀은 최근 온보딩 인원이 많아졌다. 신입이나 다른 팀에서 온 사람들이 "주간 한도가 뭐고, 그럼 폴백은 어떻게 되는 건데?"라고 물을 때, 나는 더 이상 "코드를 읽어봐" 또는 "우리가 그렇게 짜뒀어" 같은 답을 할 수 없다. 대신 문서를 가리킬 수 있다. 그리고 문서는 코드보다 훨씬 빠르게 이해된다.

또 운영 관점에서 보면, 이런 폴백 메커니즘은 의도된 동작(intended behavior)이다. 버그가 아니다. 그런데 문서가 없으면, 모니터링 알람이나 로그에서 "어? 이상한 패턴이 보이는데?" 하고 의심받을 수 있다. 문서가 있으면 "아, 이건 맞다. 의도된 폴백이구나"라고 신속하게 판단할 수 있다.

한 가지 더 배운 점

이번 작업은 "코드를 짜는 일"이 아니라 "팀과 시스템을 더 투명하게 만드는 일"이었다. 폴백 메커니즘 자체는 이미 있었고, 작동도 했다. 다만 누구나 쉽게 이해할 수 있도록 구조를 명시하고, 언제 어떤 상황에 어느 단계가 발동되는지 기록했을 뿐이다.

좋은 코드와 좋은 문서는 같은 무게를 가진다. 어떨 땐 문서가 더 중요할 수도 있다. 왜냐하면 코드는 작동하는 사람만 이해하고, 문서는 팀 전체가 함께 이해하기 때문이다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 커피머신 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.