오류 종류마다 재시도 규칙이 달라

상태 코드가 책임자를 가리켜

Anthropic API는 표준 HTTP 상태와 구조화된 JSON 오류를 돌려줘. 400은 요청 형식 문제, 401/403은 인증 문제, 429는 호출 한도 초과야. 500/503은 서버 오류이고 529는 과부하를 뜻해. SDK의 타입이 있는 예외를 잡으면 본문 문자열을 직접 해석하지 않아도 돼.

일반 요청과 스트리밍은 같은 재시도를 쓸 수 없어

일반 POST는 429나 5xx에서 다시 보내기 비교적 안전하고, SDK도 기본 max_retries 값 2까지 처리해. 스트리밍은 일부 결과가 이미 소비됐을 수 있어 처음부터 다시 보내면 중복 출력이나 중복 작업이 생겨. 길고 비싼 생성은 무작정 재시도하기보다 이어서 수행하는 절차를 설계해.

도착 여부를 모를 때는 멱등성 키를 써

Messages API는 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},
)

상태 코드가 책임자를 가리켜

일반 요청과 스트리밍은 같은 재시도를 쓸 수 없어

도착 여부를 모를 때는 멱등성 키를 써

Code

External links

Exercise

Progress

댓글 0