한 장의 그림으로 이해하기

그림 크게 보기 ↗ (새 탭)
모델·API · 판정 관망
그림을 글로 풀면
같은 오류 번호, 다른 대응
429 응답의 상세 원인과 대기 안내를 함께 확인합니다.
- 대상
- Claude API를 연결하는 개발자
- 무엇이 바뀜
- 속도 제한과 월 지출 상한은 다릅니다.
- 왜 중요한가
- 짧은 재시도로 풀리지 않는 제한이 있습니다.
- 지금 할 일
- 오류 상세와 응답 헤더를 대조합니다.
- 한계·미확인
- 개념 비유입니다. API 호출·복구 시험은 하지 않았습니다.
- 확인일
- 2026-09-21
재시도 목록에 원인 칸을 더하기
가상의 문서 처리 앱에서 같은 429 오류가 반복된다고 가정합니다. 이 글은 실패 기록에 상태 코드뿐 아니라 오류 상세와 응답 헤더를 함께 남기는 방법을 제안합니다. 그림처럼 대기해야 할 요청과 사용 한도를 확인할 요청을 나누면, 모든 실패를 같은 짧은 주기로 반복하는 설계를 피할 수 있습니다.
대기 안내가 있는 속도 제한
공식 문서는 요청 수·입력 토큰·출력 토큰의 속도 제한을 넘으면 429와 대기 안내 헤더 retry-after를 돌려준다고 설명합니다. 이 헤더는 다시 시도하기까지 기다릴 초 단위 시간을 나타냅니다. 순간적인 요청 집중도 제한에 걸릴 수 있으므로 분당 총량만 보고 여유가 있다고 단정하지 않습니다. 안내 시간이 지나도 다음 요청의 성공을 보장하는 것은 아닙니다.
월 지출 상한이면 별도 확인하기
조직 등급의 월 지출 상한에 도달한 경우에도 429가 올 수 있지만, 문서상 이 응답에는 retry-after가 없습니다. Messages API의 상세 코드 enforced_spend_limit_reached로 구분할 수 있습니다. 짧게 반복 호출해도 접근이 재개되기 전에는 풀리지 않으므로 요청을 보류하고 관리자에게 사용 현황을 확인하는 절차를 제안합니다. 사용자가 직접 설정한 지출 한도는 문서에서 400으로 설명하므로 모든 한도 오류를 429로 묶지 않습니다. 한도 변경이나 실제 재시도 시험은 수행하지 않았습니다.
참고 원문: Claude API Rate limits 공식 문서 · 원문 게시일 상시 문서(게시일 별도 미표기) · 확인일 2026-09-21
AI 작성·자동 검증: 공식 자료와의 대조 및 게시 구조 검사. 사람의 개별 검수와 제품 실행 시험은 수행하지 않았습니다. 그림은 신규 생성한 개념 일러스트입니다.
이 글의 검증 카드
- 자료 버전
- Claude Messages API Rate limits 상시 문서·2026-09-21 확인. 실제 API 오류 재현 없음
- 확인일
- 2026-09-21
- 검증 상태
- 개발자 주장
- 한계·주의
- 개념 비유입니다. API 호출·복구 시험은 하지 않았습니다.
함께 더 정확하게
질문·오류 제보
그림에서 이해되지 않는 부분이나 달라진 내용을 알려 주세요. 관리자가 확인하고 승인한 글만 공개됩니다.
개발에서는 이메일 인증 가입 또는 관리자 발급 계정으로 참여할 수 있습니다. 계정·이용 문의
아직 계정이 없으신가요? 회원가입
공개된 질문·제보
아직 공개된 질문·제보가 없습니다. 궁금한 부분을 먼저 남겨 주세요.