---
title: "key-carousel: LLM API 키 풀 관리 + 자동 로테이션 + 지수 백오프 라이브러리"
published: 2026-03-06T22:44:01.000Z
canonical: https://jeff.news/article/275
---
# key-carousel: LLM API 키 풀 관리 + 자동 로테이션 + 지수 백오프 라이브러리

여러 LLM 에이전트를 운영할 때 API 키 레이트 리밋 문제를 해결하는 TypeScript 라이브러리. 키 풀 관리, 자동 로테이션, 지수 백오프 쿨다운, 프로바이더 간 폴백을 제공함.

- LLM 에이전트 여러 개 돌리다 보면 API 키 하나가 레이트 리밋 걸리면서 전체 시스템이 멈추는 경험, 다들 있을 거임. key-carousel은 이 문제를 해결하는 TypeScript 라이브러리로, API 키 풀을 관리하면서 자동 로테이션 + 지수 백오프 쿨다운 + 프로바이더 간 폴백을 처리해줌
- 쿨다운이 꽤 세심하게 설계되어 있음. 일반 에러는 1분 → 5분 → 25분 → 최대 1시간(60s × 5^n), 빌링 에러는 5시간 → 10시간 → 20시간 → 최대 24시간(5h × 2^n)으로 별도 관리. 돈 문제는 금방 안 풀리니까 길게 가는 거임
- 에러 분류도 자동으로 해줌: HTTP 상태 코드(401→인증, 402→빌링, 429→레이트 리밋 등) + 메시지 패턴("rate limit", "quota exceeded" 등) + 에러 타입(AbortError→타임아웃) 기반. 명시적으로 `FailoverError`를 던지면 "다음 프로필로 재시도"를 직접 제어할 수도 있음
- `storagePath` 옵션으로 쿨다운 상태를 파일에 영속화할 수 있어서 프로세스 재시작해도 상태가 유지됨. 원자적 쓰기(temp + rename)로 저장하고, 파일 락으로 동시 접근 처리
- LiteLLM과 비교하면: LiteLLM은 별도 프록시 서버 + Python + DB가 필요한 반면, key-carousel은 인프라 제로, TypeScript 네이티브, ESM, 의존성 없음. 프로덕션 AI 게이트웨이에서 수십 개 에이전트를 돌리면서 추출했다고 함

> [!TIP]
> TypeScript로 LLM 에이전트 여러 개 돌리면서 키 관리에 고통받고 있다면, LiteLLM 프록시 올리기 전에 한번 볼 만한 라이브러리. 의존성 제로에 인프라 불필요라서 부담이 없음

## 핵심 포인트

- 일반 에러와 빌링 에러의 쿨다운을 별도 관리 (빌링은 5h~24h)
- 인프라 제로, 의존성 제로 — LiteLLM 프록시 대비 가벼움
- 프로세스 재시작 시에도 쿨다운 상태 영속화 지원

## 인사이트

LLM 에이전트 멀티 키 관리라는 실제 통증 포인트를 정확히 짚은 도구. LiteLLM까지 올리기엔 과한 경우에 딱 맞음.