Claude API 500 api_error 및 502 Bad Gateway — 실제로 복구되는 재시도 정책

500과 502는 제한이 아니라 장애를 의미합니다. 따라서 이 오류군에서 거의 즉시 재시도할 가치가 있는 유일한 오류 유형입니다. 429는 자체 속도 제한이고 529는 공급자 용량 초과입니다. 셋 중 잘못된 오류를 재시도하면 작은 장애가 여러분의 장애로 커집니다.

오류

two shapes, same remedy

// Straight from the model provider (HTTP 500)
{
  "type": "error",
  "error": { "type": "api_error", "message": "Internal server error" }
}

// From a gateway or proxy in between (HTTP 502)
{
  "error": {
    "message": "Failed to reach upstream provider",
    "type": "upstream_error",
    "code": "upstream_error",
    "param": null
  }
}

원인과 해결 방법 한눈에 보기

원인	해결 방법
일시적인 공급자 측 장애	지수 백오프와 지터를 사용하여 최대 약 5회까지 재시도하세요.
연결은 수락되었지만 응답이 없음	오류가 아니라 멈춤입니다. 첫 바이트까지의 시간을 전체 지속 시간과 별도로 제한하세요.
중개자가 자체 502를 반환함	모델과는 관계가 없습니다. 본문이 공급자의 형식인지 프록시의 형식인지 확인하세요.
실제 장애 중 맹목적으로 재시도함	시도 횟수를 제한하고 백오프를 적용하세요. 그렇지 않으면 재시도가 장애의 일부가 됩니다.

해결책을 선택하기 전에 500을 529 및 429와 구분하세요

429는 여러분이 초과하고 있는 속도 제한입니다 — 속도를 낮추세요. 529는 공급자의 용량 초과입니다 — 훨씬 더 강하고 오래 백오프하세요. 500/502는 장애로, 대개 짧고 특정 요청에 국한됩니다. 빠르게 재시도할 가치가 있는 것은 세 번째 유형뿐이며, 세 가지를 모두 동일하게 취급하면 재시도 루프가 장애를 악화시킵니다.

5xx는 재시도하고 4xx는 절대 재시도하지 마세요

지수 백오프와 지터를 사용하고 최대 5회까지 시도하세요. 동일한 헬퍼를 모든 공급자에 사용할 수 있습니다. 400 또는 422는 다음 시도에서도 똑같이 실패하므로 재시도해도 같은 오류에 도달하는 데 지연만 추가됩니다.

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

첫 바이트까지의 시간을 전체 지속 시간과 별도로 제한하세요

전체 요청에 타임아웃 하나만 설정하면 긴 생성과 끊어진 연결을 구분할 수 없습니다. 첫 바이트에는 짧은 기한을, 나머지에는 넉넉한 기한을 설정하세요. 그러면 멈춤은 빠르게 실패하고 실제로 느린 응답은 그대로 기다릴 수 있습니다.

시도별 상태와 지연 시간을 기록하세요

시도별 기록이 없으면 사후에 공급자 장애와 자체 타임아웃이 똑같아 보입니다. 상태 코드, 지연 시간 및 시도 번호만 있으면 다음 날 둘을 구분할 수 있습니다.

Kunavo를 통해 호출하는 경우

2026년 9월 현재 Kunavo의 모든 Claude 모델은 단일 업스트림 채널을 통해 제공되므로 해당 채널의 5xx는 요청 내부에서 재시도되지 않습니다. 대신 “Upstream provider error” 메시지를 포함한 502로 여러분에게 전달되며(/v1/messages에서는 api_error 유형), 요청 비용은 0으로 기록됩니다. Kunavo의 요청 내부 재시도는 두 번째 채널이 구성된 모델에만 실행됩니다. 이 경우 타임아웃, 5xx, 429 또는 Kunavo 자체 업스트림 키 거부가 발생하면 여러분에게 전달되기 전에 해당 채널에서 재시도됩니다. 대상은 /v1/messages, /v1/responses 및 /v1/chat/completions의 Claude 모델입니다. 스트림은 첫 콘텐츠가 도착할 때까지 보류되므로 시작되지 않은 스트림 내부의 오류도 재시도됩니다. 콘텐츠가 흐르기 시작한 후의 중간 스트림 장애는 여러분이 처리해야 합니다. 어느 경우든 이 페이지의 재시도 정책을 여러분의 측에서도 유지하세요. 이 동작을 뒷받침하는 라우팅은 다음에 설명되어 있습니다: AI 게이트웨이 가이드.

자주 묻는 질문

500을 반환하는 요청에도 요금이 청구되나요?

Kunavo에서는 아닙니다 — 실패한 요청은 비용 0으로 기록됩니다. 공급자와 직접 결제하는 경우에는 다르지만, 일반적으로 5xx에는 요금이 부과되지 않습니다.

500을 재시도하면 두 개의 완료 결과가 생성될 수 있나요?

예. 모델이 이미 생성한 후 요청이 실패할 수 있습니다. 작업에 부작용이 있다면 재시도를 추가하기 전에 여러분의 계층에서 멱등성을 보장하세요.

500, 502 및 529의 한 줄 차이는 무엇인가요?

500은 공급자 자체의 장애, 502는 앞단의 무언가가 공급자에 도달하지 못한 장애, 529는 공급자의 용량 초과입니다 — 처음 두 가지는 곧 재시도하고 세 번째는 훨씬 나중에 재시도하세요.