OpenAI 호환 API에서의 429 Rate Limit 에러: 모델을 교체하기 전 재시도(Retries) 디버깅하기

429 에러는 오해하기 쉽습니다.

가장 먼저 드는 생각은 보통 이렇습니다:

"제공업체(Provider)가 불안정하구나."

때로는 그것이 사실일 수도 있습니다. 하지만 OpenAI 호환 API 시스템에서 429 에러는 훨씬 더 국소적인 문제에서 발생할 수도 있습니다:

너무 많은 동시 요청 (Concurrent requests);
너무 공격적으로 발생하는 재시도 (Retries);
예상보다 더 많은 호출을 생성하는 에이전트 루프 (Agent loop);
트래픽을 증폭시키는 폴백 모델 (Fallback models);
여러 환경에서 하나의 공유 키를 사용하는 경우;
배치 작업 (Batch job)과 프로덕션 앱이 동일한 프로젝트를 사용하는 경우;
모델, 경로(Route), 또는 업스트림 제공업체(Upstream provider)에 따라 다른 속도 제한 (Rate limits).

모델이나 게이트웨이를 교체하기 전에, 압박이 어디에서 오고 있는지 증명하십시오.

1. 사용자 트래픽과 백그라운드 트래픽 분리하기

만약 프로덕션 앱, 크론 잡 (Cron job), 평가 스크립트 (Evaluation script), 임베딩 배치 (Embedding batch), 그리고 데모가 모두 동일한 API 키를 사용한다면, 429 에러는 어떤 워크로드(Workload)가 압박을 가했는지 알려주지 않습니다.

가능한 경우 별도의 프로젝트 키를 생성하십시오:

프로덕션 사용자 트래픽용 하나;
스테이징 (Staging)용 하나;
임베딩 또는 배치 작업용 하나;
실험용 하나;
데모 또는 공개 예제용 하나.

이렇게 하면 첫 번째 질문에 답할 수 있게 됩니다:

어떤 워크로드가 제한에 걸렸는가?

모든 트래픽이 하나의 키를 공유한다면, 당신은 군중 속에서 디버깅을 하고 있는 것입니다.

2. 사용자 액션당 호출 횟수 계산하기

현대적인 AI 앱은 사용자의 클릭 한 번당 모델 요청을 단 한 번만 보내는 경우가 드뭅니다.

하나의 사용자 액션은 다음과 같은 것들을 생성할 수 있습니다:

라우터/분류기 (Router/classifier) 호출;
검색 (Retrieval) 또는 쿼리 재작성 (Query rewrite);
메인 채팅 완성 (Main chat completion);
도구 호출 (Tool calls);
재시도 (Retries);
폴백 모델 (Fallback model) 호출;
모더레이션 (Moderation) 또는 검증 (Validation) 호출;
로깅 (Logging) 또는 평가 (Evaluation) 호출.

만약 페이지에서 분당 10번의 사용자 액션이 일어나는데 백엔드에서 분당 120번의 모델 요청을 보낸다면, 속도 제한 (Rate-limit) 문제는 단순한 트래픽 문제가 아닙니다.

그것은 증폭 (Amplification)입니다.

이는 특히 에이전트 (Agents) 및 RAG 워크플로우에서 흔히 발생합니다.

3. 백오프 (Backoff)를 추가하되, 문제를 숨기지는 마십시오

지수 백오프 (Exponential backoff)는 유용합니다. 지터 (Jitter)도 유용합니다. 재시도 헤더 (Retry headers)를 준수하는 것도 유용합니다.

하지만 재시도는 실제 실패 모드 (Failure mode)를 숨길 수도 있습니다.

추적하십시오:

각 사용자 작업이 얼마나 많은 시도(attempts)를 생성하는지;
재시도 불가능한 에러 (non-retryable error) 이후에 동일한 요청이 재시도되는지;
여러 워커 (workers)가 동시에 재시도하는지;
모든 속도 제한 (rate-limit) 에러 이후에 폴백 (fallback)이 실행되는지;
재시도가 성공하지만 비용이 두 배로 발생하는지.

세 번의 시도 끝에 성공하는 재시도 역시 운영상의 신호 (operational signal)입니다.

또한, 이는 비용이 많이 드는 신호일 수도 있습니다.

4. 스트리밍 버그와 속도 제한을 혼동하지 마세요

스트리밍 (Streaming)은 실패를 다르게 보이게 만듭니다.

다음과 같은 현상이 나타날 수 있습니다:

요청이 시작되었으나 나중에 실패함;
클라이언트가 연결을 끊고 재시도함;
서버가 부분적인 출력 (partial output) 이후에 재시도함;
UI가 요청이 실패했다고 판단하여 중복 요청을 보냄;
첫 번째 실패한 스트림에서 사용량 데이터 (usage data)가 누락됨.

스트리밍을 디버깅하기 전에, 동일한 베이스 URL (base URL), API 키 (API key), 모델 ID (model ID)를 사용하여 작은 규모의 비스트리밍 (non-streaming) 요청을 실행해 보세요.

비스트리밍 요청은 성공하지만 스트리밍이 실패한다면, 문제의 범위가 좁혀진 것입니다.

둘 다 실패한다면, 베이스 경로 (base route), 키 (key), 모델 (model), 그리고 제한 상태 (limit state)를 계속 디버깅하십시오.

5. 정확한 모델과 경로를 조사하세요

속도 제한 (Rate limits)은 항상 균일하지 않습니다.

두 개의 모델 ID는 서로 다른 제한을 가질 수 있습니다. 게이트웨이 경로 (gateway route)는 예상과 다른 업스트림 (upstream)을 가질 수 있습니다. 폴백 (fallback)은 트래픽을 다른 제한을 가진 다른 모델로 이동시킬 수 있습니다.

유용한 로그에는 다음 내용이 표시되어야 합니다:

요청된 모델 ID (requested model ID);
라우팅된 모델 또는 업스트림 제공자 (upstream provider);
프로젝트 키 (project key);
상태 코드 (status code);
재시도 횟수 (retry count);
폴백 횟수 (fallback count);
입력 및 출력 토큰 (input and output tokens);
요청 타임스탬프 (request timestamp);
에러가 모델 라우팅 (model routing) 전 또는 후에 발생했는지 여부.

로그가 이러한 질문에 답할 수 없다면, 다음 모델 교체는 대부분 추측에 의존하게 됩니다.

6. 429 에러를 디버깅하는 동안 비용을 주시하세요

속도 제한 (rate-limit) 사고는 비용 사고로 이어질 수 있습니다.

일반적인 패턴:

재시도로 인해 유료 성공 요청 수가 세 배로 증가함;
폴백 (fallback)이 더 비싼 모델을 사용함;
긴 프롬프트 (long prompts)가 계속해서 다시 전송됨;
에이전트 루프 (agent loops)가 도구 호출 (tool calls)을 반복함;
사용자가 더 이상 신경 쓰지 않는데도 백그라운드 작업 (background jobs)이 계속 재시도함.

재시도(retry)가 결국 성공했는지 여부만 묻지 마세요.

다음 질문을 던지세요:

재시도와 폴백(fallback)을 거친 후, 단 한 번의 성공적인 사용자 작업에 비용이 얼마나 들었는가?

7. 소규모 압박 테스트 (pressure test) 사용

프로덕션 트래픽(production traffic)을 옮기기 전에, 작고 통제된 테스트를 실행하세요:

단일 요청 (one request)
5개의 순차적 요청 (five sequential requests)
5개의 동시 요청 (five concurrent requests)
스트리밍 (streaming)을 적용한 동일 테스트
재시도 (retry)를 활성화한 동일 테스트
폴백 (fallback)을 활성화한 동일 테스트
실제 사용자 워크플로우(workflow)를 처음부터 끝까지 한 번 수행

성공 여부, 상태 코드 (status code), 지연 시간 (latency), 재시도 횟수 (retries), 모델 ID (model ID), 그리고 토큰 비용 (token cost)을 기록하세요.

거대한 벤치마크 (benchmark)가 필요한 것이 아닙니다. 프로덕션 환경에서 예상치 못한 동작이 발생하는 것을 방지할 수 있을 만큼의 충분한 증거가 필요할 뿐입니다.

Practical TackleKey 설정

TackleKey는 OpenAI 호환 엔드포인트 (OpenAI-compatible endpoint)를 제공합니다:

429 디버깅을 위한 유용한 페이지는 다음과 같습니다:

429 트러블슈팅 (troubleshooting): https://tacklekey.com/troubleshooting/429-rate-limit?utm_source=devto&utm_medium=article&utm_campaign=429_rate_limit_debug
API 에러 트러블슈팅 (troubleshooting): https://tacklekey.com/troubleshooting/openai-compatible-api-errors?utm_source=devto&utm_medium=article&utm_campaign=429_rate_limit_debug
에이전트 (agent) API 비용 제어: https://tacklekey.com/solutions/ai-agent-api-cost-control?utm_source=devto&utm_medium=article&utm_campaign=429_rate_limit_debug
모델 디렉토리 (model directory): https://tacklekey.com/models?utm_source=devto&utm_medium=article&utm_campaign=429_rate_limit_debug
examples: https://tacklekey.com/examples?utm_source=devto&utm_medium=article&utm_campaign=429_rate_limit_debug

목표는 단순히 에러를 사라지게 만드는 것이 아닙니다.

목표는 어떤 프로젝트, 모델, 경로(route), 재시도 정책(retry policy), 그리고 사용자 워크플로우(user workflow)가 해당 에러를 발생시켰는지 이해하는 것입니다.

Insights