본문으로 건너뛰기

오류, 속도 제한 & 안정성

중급
What you'll learn
  • HTTP 오류 지도를 읽고 재시도할 상태와 수정할 상태를 구분하기
  • 지수 백오프와 지터로 일시적 오류를 재시도하되 상한 두기
  • retry-after, 스무딩, 배치 처리, 저렴한 모델로 속도 제한 다루기
  • 모델 지원 중단과 마이그레이션으로부터 코드 보호하기

프로덕션 코드는 네트워크 서비스와 통신하므로 실패를 예상해야 합니다. 여기서 약간의 구조가 불안정한 통합과 신뢰할 수 있는 통합의 차이를 만듭니다.

오류 지도​

여러분이 처리하게 될 일반적인 HTTP 상태:

상태의미할 일
400잘못된 요청페이로드를 수정하세요; 그대로 재시도하지 마세요
401잘못되거나 누락된 API 키자격 증명을 확인하세요
403허용되지 않음접근/권한을 확인하세요
429속도 제한백오프 후 재시도 (retry-after 존중)
500/529서버 오류 / 과부하백오프 후 재시도
Pro tip
  • 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))
Watch out
  • 많은 SDK가 일시적 오류를 자동으로 재시도합니다 — 여러분만의 재시도를 추가하기 전에 클라이언트의 기본 동작을 파악하세요. 그렇지 않으면 재시도가 중복될 수 있습니다.

속도 제한​

제한은 계정/등급별로 적용됩니다(분당 요청 수와 토큰 수). 제한에 도달하면 타이밍 힌트와 함께 429를 받습니다. 상한 아래에 머무는 전략:

Guided walkthrough1 of 4
  1. 429를 받으면 응답의 타이밍 힌트를 읽고 그만큼 기다린 뒤 재시도하세요.

대용량 단계에 알맞은 모델을 고르려면 모델 선택을 참고하세요.

모델 마이그레이션​

모델 ID는 날짜/버전이 붙어 있고 지원이 중단됩니다. 스스로를 보호하세요:

Key takeaways
  • 400/401/403은 여러분 잘못입니다 — 요청이나 자격 증명을 수정하세요, 무작정 재시도하지 마세요. 429와 500/529는 재시도 가능합니다.
  • 일시적 오류는 지수 백오프 + 지터로 상한을 두고 재시도하세요(예: min(2 ** attempt + random(), 30)).
  • 429에서는: retry-after를 존중하고, 버스트를 스무딩하고, 오프라인 작업을 배치화하고, 대용량 단계를 저렴한 모델로 라우팅하세요.
  • 모델 ID를 설정에서 읽고, 지원 중단을 주시하고, 모델을 마이그레이션할 때 평가를 다시 실행하세요.

스스로 점검하기

0/4
  1. 400 잘못된 요청을 받았습니다. 무엇을 해야 하나요?
  2. 백오프로 재시도해야 하는 상태는 어느 것인가요?
  3. 지수 백오프에 지터를 더하는 이유는?
  4. 제안된 속도 제한 전략이 아닌 것은?

다음​