429 오류가 발생했다고 급히 모델을 바꾸지 마세요: 3단계로 속도 제한 출처를 판단하고, 백오프와 장애 조치를 위한 5가지 설정하기

작성자 노트: 429를 만났다고 해서 바로 모델을 바꿀 필요는 없어요. 이 글에서는 3단계 점검으로 레이트 리밋이 업스트림 공급자, 게이트웨이, 무료 티어 중 어디서 발생했는지 판단하고, 지수 백오프와 Retry-After, 장애 조치 구성 방법까지 알려드릴게요.

새벽에 배치 작업을 돌리던 중 로그에 갑자기 429 Too Many Requests가 한 화면 가득 찍히면, 많은 사람이 가장 먼저 “이 모델은 안 되니 얼른 다른 모델로 바꿔야겠다”고 생각해요. 하지만 이 판단은 대개 너무 이른 판단이에요. 429는 “누군가 당신을 제한했다”는 것만 알려줄 뿐, 누가 제한했는지, 어떤 기준으로 제한했는지는 알려주지 않아요. 이 글의 핵심은 레이트 리밋의 출처를 먼저 파악한 뒤, 백오프할지 전환할지 결정하세요라는 점이에요.

이 글은 재시도에 관한 뻔한 개론이 아니에요. 실제 트러블슈팅 순서대로 오류 메시지, 응답 헤더, 레이트 리밋 기준을 뜯어보고, 이어서 백오프 파라미터와 장애 조치 체인의 구성 권장안을 제시할게요.

핵심 가치: 이 글을 읽고 나면 몇 분 안에 429가 업스트림 공급자, 중간 게이트웨이, 무료 티어 할당량 중 어디서 온 건지 판단할 수 있고, 내 애플리케이션에 “기다려야 할 때는 기다리고, 전환해야 할 때는 전환하는” 장애 허용 전략을 갖출 수 있어요.

429 속도 제한 판단 핵심 포인트

429는 HTTP 표준에서의 ‘요청 과다’ 상태 코드예요. 대규모 언어 모델 API 상황에서는 호출 체인의 어느 계층에서든 반환될 수 있어요. 아래 표는 가장 흔한 세 가지 출처와 각각에 대응하는 올바른 처리 방식을 정리한 것이에요.

속도 제한 출처	대표적 특징	모델 교체 필요 여부	권장 처리
업스트림 모델 제공사	오류 본문에 제공사 자체의 오류 유형과 문구가 포함되고, 응답 헤더에 제공사의 속도 제한 필드가 있음	보통 불필요	Retry-After에 따라 백오프하고, 필요 시 동시성을 낮추거나 할당량 증액을 신청
중간 게이트웨이/집계 플랫폼	오류 문구가 게이트웨이에서 비롯되며, 계정 수준 또는 그룹 수준의 속도를 안내함	불필요	게이트웨이 측 할당량과 동시성 설정을 확인하거나, 게이트웨이 그룹을 전환
무료 등급/체험 할당량	무료 할당량, 일일 횟수 또는 용량 부족을 안내함	상황에 따라	유료 등급으로 업그레이드하거나, 여유 용량이 있는 동급 모델로 전환

429가 모델 장애와 같지 않은 이유

모델 자체를 사용할 수 없을 때 더 흔히 나타나는 신호는 5xx 계열 오류예요. 예를 들어 Anthropic의 과부하는 529 overloaded_error를 반환하고, 게이트웨이나 로드 밸런서 이상에서는 502, 503이 흔히 나타나요. 이런 상태 코드는 서버 측이 일시적으로 처리를 감당하지 못한다는 뜻이며, ‘당신의 계정이 할당량을 초과했다’는 것과는 전혀 다른 얘기예요.

반면 429는 명확한 귀속 의미를 담고 있어요. 속도 제한 규칙이 바로 당신을 향한다는 뜻이죠. 당신의 API 키일 수도, 당신의 조직일 수도, 당신이 속한 무료 등급일 수도, 게이트웨이가 당신에게 할당한 속도일 수도 있어요. 모델을 바꾸면 가끔 피할 수 있지만, 속도 제한이 게이트웨이 계정 수준 할당량에서 비롯된 것이라면 모델을 바꿔도 똑같이 벽에 부딪혀요. 만약 속도 제한이 업스트림 제공사의 분당 토큰 상한에서 비롯된 것이라면 몇 초만 기다리면 회복되고, 모델을 바꾸는 쪽이 오히려 출력 품질의 불확실성을 불러들여요.

제3자가 정리한 Claude Code 트러블슈팅 자료도 이 점을 뒷받침해요. Claude Code가 429를 만나면 Request rejected (429)를 표시하고 그 뒤에 서버 측 원문 문구를 붙이는데, 바로 이 문구가 속도 제한이 Anthropic에서 왔는지, 게이트웨이에서 왔는지, 아니면 무료 등급에서 왔는지를 알려줘요. 그러니 문제 해결의 첫 단계는 언제나 전체 오류 메시지를 읽는 것이지, 상태 코드만 슬쩍 보는 게 아니에요.

429와 인접 상태 코드의 차이

서로 다른 오류를 한데 뭉뚱그리지 않기 위해, 아래 표는 대규모 언어 모델 호출에서 429와 혼동하기 쉬운 몇 가지 상태 코드를 정리했어요.

상태 코드	의미	책임 주체	재시도 적합 여부	페일오버 적합 여부
429	요청 과다로 속도 제한 또는 할당량 제한 발생	호출자 할당량	적합, 백오프 필요	백오프가 효과 없으면 전환
529	업스트림 과부하(Anthropic 전용)	서버 측 용량	적합, 짧은 백오프	적합
503	서비스 일시 사용 불가	서버 또는 게이트웨이	적합	적합
500/502	내부 오류 또는 게이트웨이 오류	서버 또는 게이트웨이	제한된 횟수 재시도	적합
400/401/403	매개변수, 인증 또는 권한 문제	호출자 설정	부적합	부적합, 설정 수정 필요

이 표에서 놓치기 쉬운 디테일이 하나 있어요. Claude Code의 fallbackModel 메커니즘은 서드파티 테스트에 따르면 529 과부하일 때만 작동하며, 최대 3개의 대체 모델을 시도할 뿐 429에서는 작동하지 않아요. 이를 보면 도구 설계자들도 429의 첫 반응은 모델을 바꾸는 것이 아니라 백오프여야 한다고 보고 있다는 걸 알 수 있어요.

429 속도 제한이 어디서 발생했는지 판별하는 방법: 3단계 점검

아래는 바로 따라 할 수 있는 429 점검 절차예요. 세 단계는 비용이 낮은 순서부터 높은 순서로 배열되어 있고, 대부분의 경우 첫 번째 단계에서 원인을 찾을 수 있어요.

1단계: 429 오류 본문 전체 읽기

상태 코드만 로그에 남기지 말고 응답 본문을 그대로 기록하세요. 계층마다 반환하는 429의 문구가 뚜렷하게 달라서, 이게 가장 직접적인 단서가 돼요.

업스트림 공급자 반환: 오류 본문에 보통 공급자의 오류 유형 필드가 포함돼요. 예를 들어 Anthropic은 rate_limit_error 유형을, OpenAI 스타일 API는 rate_limit_exceeded 같은 오류 코드를 제공하며, 요청 수 초과인지 토큰 수 초과인지 설명해요.
게이트웨이 반환: 문구에서 “계정”, “그룹”, “토큰”, “채널” 같은 게이트웨이 자체 개념을 언급하거나 게이트웨이 이름을 명시하는 경우가 많아요.
무료 티어 반환: “free tier”, “quota”, “daily limit”, “capacity” 같은 표현이 나와요. 서드파티가 특정 모델의 무료 체험을 테스트하는 과정에서 이런 용량형 429를 자주 마주치기도 해요.

중계 서비스나 애그리게이션 플랫폼을 통해 호출한다면, 게이트웨이가 업스트림의 원본 오류를 그대로 전달했는지 특히 주의해서 봐야 해요. 그대로 전달됐다면 업스트림이 여러분을 제한하고 있다는 뜻이고, 그대로 전달되지 않은 커스텀 문구라면 게이트웨이가 여러분을 제한하고 있다는 뜻이에요.

2단계: 429 응답 헤더 점검

응답 헤더는 두 번째 판단 근거예요. 주요 제공자는 응답 헤더에 남은 할당량과 재설정 시간을 담아 보내고, 게이트웨이도 자체 필드를 함께 넣을 수 있어요.

응답 헤더	일반적인 출처	의미	점검 용도
`Retry-After`	HTTP 표준, 여러 곳에서 사용	기다리라는 권장 시간(초)	백오프 시 우선 적용
`x-ratelimit-remaining-requests`	OpenAI 스타일 API	현재 윈도우의 남은 요청 수	RPM 속도 제한인지 판단
`x-ratelimit-remaining-tokens`	OpenAI 스타일 API	현재 윈도우의 남은 토큰 수	TPM 속도 제한인지 판단
`anthropic-ratelimit-requests-remaining`	Anthropic	남은 요청 수	Anthropic에서 온 속도 제한인지 확인
`anthropic-ratelimit-input-tokens-remaining`	Anthropic	남은 입력 토큰 수	입력 토큰 속도 제한인지 판단

판단 규칙은 간단해요. 제공자 접두사가 붙은 속도 제한 헤더가 있고 남은 값이 0이라면, 기본적으로 업스트림 제공자가 속도를 제한하고 있다고 볼 수 있어요. 제공자 속도 제한 헤더가 전혀 없고 게이트웨이 자체 필드만 있거나 아무 정보도 없다면 게이트웨이 계층일 가능성이 더 커요. 다만 일부 제공자는 최근 구체적인 한도를 콘솔에서만 보여 주도록 바꿔서 응답 헤더의 정보가 불완전할 수 있어요. 이때는 1단계의 오류 문구와 3단계의 차원 비교로 돌아가야 해요.

3단계: 레이트 리밋 기준을 대조하기

누가 제한을 걸고 있는지 알았다면, 이제는 무엇이 제한되는지도 파악해야 해요. 제공사마다 레이트 리밋 규칙이 달라서, 5개 제공사를 비교한 제3자 정리 자료를 보면 이렇습니다. Anthropic은 주로 분당 토큰 수로 제한하고, 캐시에 히트된 토큰은 한도에 포함하지 않아요. DeepSeek은 주로 동시성 수를 제한하고, OpenAI와 Google의 구체적인 할당량은 콘솔에서 확인하는 경우가 더 많아요.

이건 구성 전략에 직접 영향을 줘요. 흔한 대응 관계는 다음과 같아요.

RPM(분당 요청 수) 초과: 여러 개의 작은 요청을 배치 요청으로 합치거나, 클라이언트에 토큰 버킷을 두고 일정한 속도로 전송하세요.
TPM(분당 토큰 수) 초과: 컨텍스트를 줄이고, 프롬프트 캐싱을 활성화하며, 긴 문서 작업은 서로 다른 시간대(시간 윈도우)로 나누세요.
동시성 수 초과: worker 수를 줄이고, 큐로 동시에 처리 중인 요청 수를 제어하세요. 단순한 백오프만으로는 효과가 제한적이에요.
일일 할당량 또는 무료 한도 소진: 백오프는 의미가 없고, 리셋을 기다리거나 요금제를 업그레이드하거나 다른 채널로 전환하는 수밖에 없어요.

4번째 상황은 “백오프가 무조건 무효인” 유일한 429이며, 최대한 빨리 식별해서 곧바로 페일오버로 넘어가야 하는 상황이에요.

429 백오프 전략은 어떻게 설정할까요

429가 복구 가능한 속도 제한에 해당한다고 확인한 뒤에는 백오프 단계로 들어가요. 백오프의 목표는 “최대한 빨리 재시도”가 아니라 “혼잡을 더 악화시키지 않으면서 최대한 빨리 복구”하는 거예요.

지수 백오프와 무작위 지터

가장 많이 쓰는 방식은 지수 백오프(Exponential Backoff)에 무작위 지터(Jitter)를 더하는 거예요. n번째 재시도의 대기 시간은 “기본 지연 × 2의 n제곱” 정도로 잡고, 여기에 무작위 값을 더한 뒤 상한을 설정해요. 무작위 지터는 여러 클라이언트의 재시도 시점을 흩어지게 해서, 같은 초에 한꺼번에 몰려 “재시도 폭풍”이 생기는 걸 막아줘요.

응답에 Retry-After가 포함되어 있다면, 직접 계산한 백오프 시간보다 이 값을 우선해야 해요. 서버가 제한 윈도우가 언제 초기화되는지 더 잘 알고 있으니, 서버가 제안한 대로 기다리는 게 대개 가장 빠른 복구 방법이에요.

백오프 파라미터 권장값

아래 표는 대부분의 대화형 및 배치 처리 시나리오에 적용할 수 있는 시작 파라미터를 정리한 거예요. 실제로 사용할 때는 업무의 지연 허용도에 맞춰 조정하면 돼요.

파라미터	권장 시작값	설명
기본 지연	1초	첫 재시도 전 대기 시간
백오프 배수	2	재시도할 때마다 대기 시간이 두 배로 증가
최대 단일 대기	30-60초	대기 시간이 무한정 늘어나지 않도록 방지
최대 재시도 횟수	3-5회	초과하면 페일오버 또는 오류 발생
무작위 지터	대기 시간의 0-100% 무작위	“풀 지터(full jitter)” 방식을 권장하며 재시도 분산
Retry-After	있으면 우선	직접 계산한 백오프 시간을 덮어씀

설정할 때 자주 놓치는 디테일이 두 가지 있어요. 첫째, 대화형 시나리오(예: 채팅 인터페이스)에서는 총 대기 시간이 너무 길어지면 안 돼요. 전체 타임아웃 예산을 정해 두고, 초과하면 바로 전환하거나 사용자에게 알리는 걸 권장해요. 둘째, 400, 401, 403 같은 설정 오류에는 백오프 재시도를 하지 마세요. 아무리 오래 기다려도 저절로 나아지지 않고, 시간과 쿼터만 낭비하게 돼요.

공식 SDK를 사용한다면, 많은 SDK가 이미 429와 5xx에 대한 자동 재시도를 내장하고 있어요. 보통 max_retries 같은 파라미터로 횟수를 제어하죠. 직접 재시도 로직을 한 겹 더 감싸기 전에 SDK의 기본 동작을 먼저 확인해서, 두 층의 재시도가 겹쳐 실제 재시도 횟수가 몇 배로 늘어나는 일을 피하세요.

429 페일오버, 어떻게 구성할까

백오프(backoff)는 “제자리에서 기다리기”이고, 페일오버(Failover)는 “다른 길로 가기”예요. 둘은 택일 관계가 아니라 순서 관계예요. 먼저 백오프하고, 백오프가 효과가 없을 때 전환하는 거죠.

언제 페일오버를 트리거할까

429가 보이자마자 무조건 전환하기보다는, 아래 조건 중 하나라도 충족될 때 전환을 트리거하는 걸 권해요.

최대 재시도 횟수에 도달했는데도 429가 계속 반환될 때
오류 문구가 일일 할당량, 무료 크레딧 소진 또는 “용량 부족”을 명확히 가리킬 때
Retry-After가 제시한 대기 시간이 비즈니스가 허용할 수 있는 상한을 넘을 때
같은 채널이 짧은 시간에 연속으로 여러 번 실패해 서킷 브레이커 임계값을 건드릴 때

OpenRouter에서 인기 모델이 429를 자주 뱉는 상황에 대한 서드파티의 처리 권고도 같은 맥락이에요. 먼저 백오프하고, 그다음 같은 인터페이스 안의 다른 모델로 페일오버하라는 거죠. 이 순서라면 원래 모델의 출력 품질을 그대로 누리면서도 서비스가 끊기지 않게 할 수 있어요.

전환 경로의 세 가지 설계

페일오버의 “예비 경로”에도 여러 층이 있고, 전환 비용은 낮은 순서대로 이렇게 나눌 수 있어요.

같은 모델, 채널만 교체: 같은 모델을 다른 API 키, 다른 그룹, 또는 다른 공급사로 돌리는 방식이에요. 출력 일관성이 가장 좋아서 1순위로 꼽혀요.
같은 벤더, 등급만 교체: 예를 들어 플래그십 모델에서 같은 시리즈의 경량 모델로 내리는 거예요. 성능은 살짝 떨어지지만 스타일은 비슷하죠.
벤더를 넘어 모델 교체: 다른 회사의 동급 모델로 옮기는 방식이에요. 가용성은 가장 높지만 프롬프트 효과와 출력 형식을 미리 검증해 둬야 해요.

여기에 서킷 브레이커(Circuit Breaker)를 한 겹 더 얹는 걸 권해요. 어떤 채널이 연속 실패로 임계값에 도달하면 쿨다운 시간 동안 아예 건너뛰고, 쿨다운이 끝나면 소량의 탐색 요청을 보내 회복되면 조금씩 트래픽을 늘리는 방식이죠. 이렇게 하면 매 요청이 일단 한 번 벽에 부딪힌 뒤에야 전환하는 일을 막을 수 있어서 전체 지연이 확 줄어요.

위 그림에서 비교한 두 전략은 실제 프로젝트에서 같은 통합 인터페이스로 검증할 수 있어요. APIYI처럼 OpenAI와 Anthropic 인터페이스 형식을 모두 지원하는 플랫폼이라면, 같은 코드에서 model 파라미터만 바꾸면 예비 모델로 전환할 수 있으니 벤더마다 SDK를 따로 관리하는 것보다 훨씬 간편하죠.

429 속도 제한 처리 빠르게 시작하기

앞선 내용을 바로 대조해 적용할 수 있는 설정 체크리스트로 정리해 볼게요. 이 글에는 코드가 없으니, 코드 리뷰나 운영 설정을 할 때 확인하는 체크리스트로 활용해 보세요.

설정 체크리스트 5가지

로그: 전체 응답 본문과 응답 헤더를 기록하고, 최소한 상태 코드, 오류 유형, 오류 문구, Retry-After, 각종 ratelimit 필드를 포함하세요.
분류: 클라이언트에서 오류를 “백오프 가능”(429 속도 제한류, 529, 503), “전환 필요”(할당량 소진, 지속적 실패), “재시도 불가”(400, 401, 403) 세 가지로 나누세요.
백오프: 앞서 설명한 파라미터 표에 따라 지수 백오프와 풀 지터(full jitter)를 설정하고, Retry-After를 우선하며, 최대 재시도 횟수와 전체 타임아웃 예산을 설정하세요.
전환 체인: “동일 모델에서 채널 변경 → 동일 벤더에서 티어 변경 → 벤더 간 모델 변경” 순서로 대체 목록을 구성하고, 각 대체 모델에서 프롬프트가 기대대로 작동하는지 미리 검증하세요.
서킷 브레이커와 알림: 채널마다 실패 임계값과 쿨다운 시간을 설정하고, 429 비율에 대한 알림도 설정하세요. 이 비율이 계속 높으면 할당량 증액을 신청하거나 동시성을 조정해야 한다는 뜻이에요.

대체 모델 체인 예시

아래 표는 일반적인 3단계 전환 체인을 보여주는 예시예요. 구체적인 모델명은 플랫폼 모델 목록을 기준으로 하고, 관련 과금은 가격 페이지를 기준으로 해주세요. 이 글에서는 구체적인 단가를 기재하지 않아요.

계층	선택 기준	인터페이스 형식	사용 가능 플랫폼	가격 기준
메인	실제 업무에서 효과가 가장 좋은 플래그십 모델	OpenAI 또는 Anthropic 형식	APIYI(apiyi.com), 공식 API	docs.apiyi.com/models 기준
1차 대체	동일 모델의 다른 채널 또는 그룹	메인과 동일	APIYI(apiyi.com), 공식 API	docs.apiyi.com/models 기준
2차 대체	같은 벤더의 경량 모델 또는 다른 벤더의 동급 모델	OpenAI 호환 형식	APIYI(apiyi.com) 등 API 애그리게이터 플랫폼	docs.apiyi.com/models 기준

연결 방식은 OpenAI 또는 Anthropic 공식 SDK를 사용한다면 보통 base_url을 플랫폼에서 제공하는 주소로, api_key를 플랫폼 키로 바꾸기만 하면 돼요. 구체적인 인터페이스 주소와 각 모델의 호출 설명은 APIYI 문서 센터 docs.apiyi.com을 기준으로 하는 것이 좋아요. 인터넷에 있는 검증되지 않은 주소를 그대로 복사하지 마세요.

🚀 빠른 시작: 429 내결함성 체인을 구성할 때는 APIYI(apiyi.com)를 통해 같은 코드로 메인 모델과 대체 모델을 연결하는 것을 권장해요. 플랫폼은 이 글에서 다루는 주요 모델의 API 호출을 제공하며 OpenAI와 Anthropic 인터페이스 형식과 호환돼요. 모델을 바꿀 때는 model 파라미터만 수정하면 돼요. 연결 문서는 docs.apiyi.com에서 확인할 수 있고, 각 모델의 입력/출력 단가, 캐시 가격, 과금 기준은 가격 페이지 docs.apiyi.com/models의 실제 데이터를 기준으로 해요.

자주 묻는 질문 FAQ

Q1: 429 속도 제한이란 무엇인가요?

429는 HTTP 표준의 Too Many Requests 상태 코드로, 호출자가 특정 시간 창 안에서 허용된 요청 수, 토큰 수, 동시 접속 수 또는 전체 할당량을 초과했음을 의미해요. “당신이 제한되었다”는 뜻이지, 모델 자체에 장애가 생겼다는 뜻은 아니에요.

Q2: 429와 529, 503은 어떻게 다른가요?

429는 호출자의 할당량 문제를 가리키며, 책임이 “당신이 너무 많이 사용했다”에 있어요. 529는 Anthropic의 과부하 오류, 503은 서비스 일시 불가 상태로, 둘 다 책임이 서버 측 용량에 있어요. 전자는 우선 백오프와 사용량 조정이 필요하고, 후자는 짧게 백오프한 뒤 바로 장애 조치로 넘어가는 편이 적합해요.

Q3: 429가 업스트림 제공사에서 온 건지 게이트웨이에서 온 건지 가장 빨리 판별하는 방법은?

먼저 오류 본문의 표현을 보세요. 제공사 오류 타입이 붙어 있으면 보통 업스트림에서 온 것이고, 계정·그룹·채널 같은 개념을 언급하면 보통 게이트웨이에서 온 것이에요. 다음으로 응답 헤더를 보세요. 제공사 접두사가 붙은 `ratelimit` 필드가 있고 남은 값이 0이라면, 사실상 업스트림이 제한하고 있다고 확인할 수 있어요.

Q4: 백오프를 여러 번 했는데도 429가 계속 풀리지 않는 이유는?

가장 흔한 원인은 속도 제한의 차원을 잘못 판단한 거예요. 일일 할당량이나 무료 크레딧이 소진된 경우라면 백오프는 효과가 없어요. 동시 접속 수 초과라면 클라이언트가 여전히 높은 동시성으로 요청을 보내고 있는 것이므로, 백오프로는 완화만 될 뿐이에요. 이럴 때는 동시성을 낮추거나 바로 장애 조치로 전환해야 해요.

Q5: 다중 모델 장애 조치 체인을 빠르게 구축하려면?

다중 모델 통합 인터페이스를 지원하는 플랫폼에서 검증하는 걸 권장해요:

1. APIYI apiyi.com 에서 계정을 등록하고 API 키를 발급받아요;
2. docs.apiyi.com 문서에 따라 `base_url`을 설정하고, OpenAI 또는 Anthropic 형식으로 연동해요;
3. 클라이언트에 주용과 예비 모델 목록을 설정하고, `model` 파라미터를 바꿔 전환해요.

이렇게 하면 주용과 예비 모델이 같은 코드를 공유하므로, 전환 체인의 테스트 비용이 훨씬 낮아져요.

Q6: 장애 조치가 비용을 통제 불능으로 만들까요?

가능성이 있어요. 예비 모델의 단가, 컨텍스트 길이, 캐시 전략이 모두 주용 모델과 다를 수 있고, 잦은 전환은 청구 구조를 바꿔요. 예비 모델마다 가격을 미리 확인하고, APIYI 가격 페이지 docs.apiyi.com/models 의 실제 데이터를 기준으로 삼으며, 전환 비율에 알람을 설정하는 걸 권장해요.

Q7: 429 처리 방안에는 어떤 알려진 한계가 있나요?

백오프는 요청 지연을 늘리므로 실시간성이 매우 중요한 시나리오에는 적합하지 않아요. 제공사 간 전환은 출력 스타일과 형식 차이를 불러올 수 있어 사전 회귀 테스트가 필요해요. 일부 제공사는 콘솔에서만 한도를 보여주고 응답 헤더 정보가 불완전해서, 문제를 추적할 때는 오류 표현과 모니터링 데이터에만 의존해야 해요.

429 속도 제한 처리 핵심 포인트 Key Takeaways

429는 제한되었다는 것만 알려줘요: 누가 제한했는지, 무엇이 제한되었는지는 알려주지 않으므로 모델 장애와 바로 동일시할 수 없어요.
먼저 오류 원문을 읽어요: 오류 본문의 표현이 업스트림, 게이트웨이, 무료 티어를 판단하는 가장 빠른 단서예요.
그다음 응답 헤더를 봐요: 벤더 접두사가 붙은 ratelimit 필드와 Retry-After가 두 번째 증거 체인이에요.
차원별로 맞춤 처리: RPM은 균일 속도, TPM은 컨텍스트 축소, 동시성은 worker 제어, 할당량 소진은 즉시 전환.
먼저 백오프 후 전환: 지수 백오프에 full jitter, Retry-After 우선, 재시도에는 상한을 둬요.
전환 체인 계층 설계: 같은 모델은 채널 교체 우선, 크로스 벤더는 모델 교체로 최후 방어, 서킷 브레이커를 함께.
통합 인터페이스로 비용 절감: APIYI의 OpenAI 및 Anthropic 형식 호환 인터페이스를 통해 하나의 코드로 주/백업 모델을 관리할 수 있어요.

정리

429를 만났을 때 올바른 순서는 “출처 파악 → 차원 판단 → 백오프 → 전환”이에요. 처음부터 모델을 바꾸는 게 아니에요:

출처 파악: 오류 본문 표현과 응답 헤더로 업스트림 벤더, 게이트웨이, 무료 티어를 구분해요.
차원 판단: 요청 수, 토큰 수, 동시성, 총 할당량 중 무엇인지 파악해서 백오프가 유효한지 결정해요.
내결함성 구성: 지수 백오프와 지터를 첫 번째 방어선으로, 계층적 장애 전환과 서킷 브레이커를 두 번째 방어선으로.

이 흐름을 로그, 오류 분류, 클라이언트 설정에 고정해 두면 429는 “한밤중 알람”에서 예측 가능하고 자가 치유되는 일상 이벤트가 돼요.

APIYI apiyi.com을 통해 주/백업 모델 전환 효과를 빠르게 검증하는 것을 추천해요. 접속 설명은 docs.apiyi.com에서 확인할 수 있고, 관련 모델 가격과 과금 기준은 docs.apiyi.com/models를 기준으로 해요.

📚 참고 자료

Rate Limit Reached in Claude Code: What Each 429 Message Means: Claude Code의 429 오류 메시지 의미 해석
링크: ofox.ai/blog
설명: 서버가 실제로 반환한 메시지를 통해 Anthropic, 게이트웨이, 무료 티어의 속도 제한을 구분하는 방법을 설명해요
Claude Code fallbackModel: 3-Tier Failover Setup: Claude Code 대체 모델 설정
링크: ofox.ai/blog
설명: fallbackModel이 529 과부하 시 작동하며 최대 3개 모델까지만 지원되고, 429와는 다르다는 점을 짚어요
LLM API Rate Limits Compared: 5개 대규모 언어 모델 업체의 속도 제한 규칙 비교
링크: ofox.ai/blog
설명: 토큰 기준, 동시성 기준, 콘솔 표시 전용 등 서로 다른 속도 제한 기준을 비교해요
APIYI 문서 센터 및 가격 페이지: 접속 안내 및 모델 과금
링크: docs.apiyi.com 및 docs.apiyi.com/models
설명: 인터페이스 형식, base_url 설정, 각 모델의 실제 가격은 이 문서를 기준으로 해요

작성자: APIYI 기술팀
기술 교류: APIYI apiyi.com 홈페이지에서 문의하시면 속도 제한과 장애 대응 실무를 함께 논의할 수 있어요. 더 많은 접속 자료는 docs.apiyi.com 문서 센터에서 확인하실 수 있어요

429 오류가 발생했다고 급히 모델을 바꾸지 마세요: 3단계로 속도 제한 출처를 판단하고, 백오프와 장애 조치를 위한 5가지 설정하기