에러 · 재시도 · 멱등성 스토리

에러 분류학

Anthropic API는 표준 HTTP 에러 코드와 구조화된 JSON 바디. 400은 너 버그(요청 모양 잘못). 401/403은 인증. 429는 레이트리밋. 500/503은 서버 측; retry. 529는 overloaded; backoff와 함께 retry. SDK가 이것들에 매칭되는 typed exception을 raise해서 너가 바디 수동 parse 안 해도 됨.

안전한 재시도 vs 두 번 청구되는 재시도

Non-streaming POST는 429/5xx에 retry 안전 — SDK가 max_retries(디폴트 2)까지 자동. Streaming 요청은 stream 중간에 안전하게 retry 안 됨 — partial output이 이미 소비됨. 길고 비싼 완성이면 retry 말고 resume으로 디자인.

멱등성 키

Messages API가 Idempotency-Key 요청 헤더로 멱등성 키 지원. 네트워크 깜빡거림으로 호출이 도달했는지 확신 못 하면 같은 키로 retry — API가 두 번 청구하지 않고 원본 응답 반환. Retry 의미가 중요한 비싼 호출엔 idempotency key 써.

원칙: Retry 자세를 호출 종류별로 결정, globally X. 싼 haiku 읽기는 5x retry 가능; 비싼 opus 생성은 idempotency key 원해.

Code

상태 코드 대신 타입으로 catch·python

from anthropic import (
    Anthropic,
    BadRequestError,
    AuthenticationError,
    PermissionDeniedError,
    NotFoundError,
    UnprocessableEntityError,
    RateLimitError,
    InternalServerError,
    APIConnectionError,
)

client = Anthropic(max_retries=2)

try:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        messages=[{"role": "user", "content": "hi"}],
    )
except BadRequestError as e:
    raise  # 너 버그 — 요청 모양 고쳐
except (AuthenticationError, PermissionDeniedError):
    raise  # auth — ops 알림
except RateLimitError as e:
    schedule_retry(after=e.response.headers.get("retry-after"))
except (InternalServerError, APIConnectionError):
    schedule_retry(after=2.0)  # transient — backoff and retry

비싼 호출에 idempotency key·python

import uuid

idem_key = f"order-{order_id}-claim-summary"  # business operation별 deterministic

resp = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[{"role": "user", "content": claim_text}],
    extra_headers={"Idempotency-Key": idem_key},
)

Exercise

Claude를 호출하는 코드 진입점 한 곳 audit. raise할 수 있는 expected exception 타입과 각각에 대한 액션을 나열. 빠진 분기와 각각을 시뮬레이트하는 integration test 추가.

Hint

코드가 generic Exception만 catch하면 failure에 대해 design한 게 아니야 — 숨긴 거지.

에러 · 재시도 · 멱등성 스토리

에러 분류학

안전한 재시도 vs 두 번 청구되는 재시도

멱등성 키

Code

External links

Exercise

Progress

댓글 0