본문으로 건너뛰기

오류, 속도 제한 & 신뢰성

중급

프로덕션 코드는 네트워크 서비스와 통신하므로 반드시 실패를 예상해야 합니다. 여기에 약간의 구조를 더하는 것이 불안정한 통합과 믿을 수 있는 통합을 가르는 차이입니다.

오류 지도​

처리하게 될 일반적인 HTTP 상태:

상태의미대처 방법
400잘못된 요청페이로드를 수정하세요; 그대로 재시도하지 마세요
401잘못되거나 누락된 API 키자격 증명을 확인하세요
403허용되지 않음접근/권한을 확인하세요
429속도 제한됨백오프 후 재시도(retry-after 준수)
500/529서버 오류 / 과부하백오프를 적용해 재시도

SDK는 이러한 오류를 타입이 지정된 예외로 노출하므로, 문자열을 파싱하는 대신 깔끔하게 분기할 수 있습니다.

백오프를 적용한 재시도​

일시적 오류(429, 5xx)에는 상한을 둔 지수 백오프 + 지터로 재시도하세요:

import time, random
for attempt in range(5):
    try:
        return client.messages.create(...)
    except (RateLimitError, APIStatusError) as e:
        if attempt == 4 or not should_retry(e):
            raise
        time.sleep(min(2 ** attempt + random.random(), 30))

(많은 SDK가 일시적 오류를 자동으로 재시도합니다 — 직접 재시도를 추가하기 전에 클라이언트의 기본 동작을 파악하세요.)

속도 제한​

제한은 계정/등급별로 적용됩니다(분당 요청 수와 토큰 수). 한도에 도달하면 타이밍 힌트와 함께 429를 받습니다. 전략: retry-after를 준수하고, 버스트를 완만하게 하며, 오프라인 작업을 배치 처리하고, 대량 처리 단계에는 더 저렴한 모델(모델 선택)을 사용하세요.

모델 마이그레이션​

모델 ID는 날짜/버전이 지정되어 있으며 사용 중단됩니다. 이를 대비해 격리하세요:

다음​