간단한 답변: 모든 실패 요청마다 Claude에서 GPT로 전환하지 마세요. 401은 인증을 수정해야 함을 의미하고, 경로 관련 404는 URL 또는 엔드포인트를 바로잡아야 함을 의미합니다. 429 또는 일시적인 5xx는 백오프와 함께 재시도할 수 있으며, 제한된 재시도 이후에도 실패한다면 호환 가능한 폴백 모델이 이어받을 수 있습니다.
중요한 예외가 하나 있습니다: error.code: invalid_request가 포함된 500 응답은 여전히 요청 자체의 문제입니다. 이를 재시도하거나, 동일하게 잘못된 페이로드를 다른 모델로 보내는 것은 버그를 감추는 일일 뿐입니다.
이 문서는 2026년 8월 20일 기준으로 CometAPI의 오류, 재시도, 기본 URL, 레이트 리밋, 모델 폴백 문서에 따라 검증되었습니다. 여기서는 오류 분류만 다룹니다. 라우트 설계, 공급자 자격 증명, 다층 페일오버에 대해서는 완전한 모델 폴백 튜토리얼과 기술 폴백 가이드를 참고하세요.
재시도 또는 실패 결정부터 시작하기
| 상태 | 일반적으로 의미 | 재시도? | 폴백? | 최초 조치 |
|---|---|---|---|---|
| 401 | 누락되었거나 잘못된 키 | 아니오 | 아니오 | Bearer 토큰 수정 |
| 404 | 잘못된 경로 또는 엔드포인트 | 아니오 | 아니오 | 기본 URL과 라우트 확인 |
| 429 | 레이트 리밋 또는 포화 | 예 | 제한 재시도 후 | 지터 백오프 적용 |
| 500 + invalid_request | 잘못된 요청 | 아니오 | 아니오 | 페이로드 수정 |
| 500/503/504/524 | 일시적 플랫폼/제공자 장애 | 예 | 제한 재시도 후 | 요청 ID 보관 |
실무에서 묻는 질문은 “Claude가 실패했는가?”가 아니라 “이 요청의 잘못된 부분을 바꾸지 않고도 다른 모델이 성공할 수 있는가?”입니다. 인증과 경로 오류는 연결 자체에 영향을 주므로 모델만 바꾼다고 해결되지 않습니다. 반면 일시적인 용량/서버 실패는 라우트별로 다를 수 있어 폴백이 도움이 될 수 있습니다.
모델을 바꾸기 전에 오류를 먼저 읽으세요
HTTP 상태를 error.code 및 error.message와 함께 사용하세요. 많은 CometAPI 오류는 다음과 같은 래퍼 형식을 사용합니다:
{
"error": {
"message": "human-readable detail and request id",
"type": "comet_api_error",
"param": "problematic_parameter_or_empty",
"code": "error_code_or_empty"
}
}
상태 코드의 첫 자리만으로 분류하지 마세요. 500에도 invalid_request가 포함될 수 있으며, 잘못된 CometAPI 경로는 깔끔한 JSON 404 대신 리디렉션이나 HTML을 반환할 수도 있습니다.
401 Unauthorized: 중단하고 인증을 수정하세요
401은 보통 API 키가 누락, 형식 오류, 만료, 잘못된 환경에서 로드되었음을 의미합니다. 헤더는 다음과 같아야 합니다:
Authorization: Bearer $COMETAPI_KEY
재시도하거나 모델을 바꾸지 마세요. 두 라우트 모두 동일한 깨진 인증을 사용합니다. 배포된 서비스가 오래된 시크릿을 로드했는지, 키에 공백이 추가되었는지, 요청이 의도한 환경에 도달하는지 확인하세요. 키를 회전하거나 다시 로드할 때는 반드시 시크릿 관리 프로세스를 따르세요.
404 Not Found: 폴백 전에 URL을 수정하세요
OpenAI 호환 요청의 기본 URL은 정확히 다음을 사용하세요:
https://api.cometapi.com/v1
/v1 누락, 경로 세그먼트 중복, 잘못된 엔드포인트는 404, 리디렉션, HTML 응답, 또는 SDK 파싱 오류를 유발할 수 있습니다. 디버깅 중에는 자동 리디렉션 따라가기를 비활성화하고 최종 요청 경로를 API 레퍼런스와 대조해 확인하세요.
응답이 명시적으로 모델을 사용할 수 없거나 찾을 수 없다고 말하는 경우, 현재의 CometAPI Models API에서 모델 ID를 확인하세요. 모든 404를 모델 부재로 취급하지 마세요. 그 정확한 신호를 캡처하고 테스트한 뒤에만 모델 전용 폴백을 추가하세요.
429 Too Many Requests: 실패 전 백오프하세요
429는 재시도 가능한 오류입니다. 지수 백오프와 지터를 사용하고, 버스트 동시성을 낮추며, 어떤 라우트가 포화되고 있는지 측정하세요. 모든 워커가 즉시 재시도하면 짧은 레이트 리밋이 더 큰 트래픽 스파이크로 확대될 수 있습니다.
소수의 제한된 재시도 이후에는, 다음 모델이 동일한 입력/출력 계약과 필요한 기능을 지원할 때 폴백이 적절할 수 있습니다. 폴백은 무료가 아닙니다. 지연을 추가하고 비용이나 동작이 달라질 수 있으므로 사용 빈도를 기록하세요.
5xx 오류: 코드를 확인한 뒤 재시도하세요
500, 503, 504, 524는 일반적으로 플랫폼/제공자 또는 타임아웃 계열의 실패를 의미합니다. 요청 ID, 엔드포인트, 모델, 타임스탬프를 보관하고 백오프와 함께 재시도하세요. 동일한 일시적 실패가 재시도 예산 내에서 계속되면 다음 호환 라우트로 이동하세요.
하지만 먼저 본문을 확인하세요. 500에 error.code: invalid_request 또는 invalid_request_error가 포함되어 있으면, 요청 본문을 수정하고 변경된 후에만 재시도하세요. 흔한 원인은 messages 필드 누락이나 선택한 엔드포인트가 허용하지 않는 공급자 전용 파라미터입니다.
코드에서 하나의 작은 정책을 사용하세요
이 Python 예시는 애플리케이션 내에서 재시도와 폴백을 관리합니다. 하나의 CometAPI 키, OpenAI 호환 기본 URL, 현재 Claude와 GPT 모델 ID에 대한 환경 변수를 사용합니다. 일시적 실패만 재시도하고, 재시도 예산이 소진되면 모델을 변경합니다.
import os, random, time
from openai import APIError, OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
max_retries=0,
)
MODELS = [os.environ["CLAUDE_MODEL"], os.environ["GPT_MODEL"]]
RETRYABLE = {429, 500, 503, 504, 524}
def complete(messages):
for model in MODELS:
for attempt in range(3):
try:
response = client.chat.completions.create(model=model, messages=messages)
return response.choices[0].message.content
except APIError as error:
status = getattr(error, "status_code", None)
code = getattr(error, "code", None)
if status in {401, 404} or code in {
"invalid_request", "invalid_request_error"
}:
raise
if status not in RETRYABLE:
raise
if attempt < 2:
time.sleep(2**attempt + random.random())
continue
break
raise RuntimeError("No configured route completed.")
print(complete([{"role": "user", "content": "Summarize this ticket."}]))
SDK의 자동 재시도는 비활성화되어 있으므로, 애플리케이션이 전체 재시도와 폴백 예산을 제어합니다. 이 제어 없이 SDK 재시도와 애플리케이션 재시도가 합쳐지면 호출 수가 기하급수적으로 늘고 최종 응답이 지연될 수 있습니다.
추측 없이 정책을 테스트하세요
| 시뮬레이션된 신호 | 기대 결과 | 발생하면 안 되는 것 |
|---|---|---|
| 401 | 즉시 예외 발생 | 재시도 및 GPT 호출 금지 |
| 404 | 즉시 예외 발생 | 잘못된 경로를 폴백으로 은폐 금지 |
| 429 | 백오프 후 폴백 | 즉시 재시도 폭주 금지 |
| 500 + invalid_request | 즉시 예외 발생 | 깨진 요청의 중복 전송 금지 |
| 503/504/524 | 백오프 후 폴백 | 무한 라우트 연쇄 금지 |
이는 정책 테스트이지, 라이브 제공자의 신뢰성에 대한 주장과는 다릅니다. 스테이징 환경에서 상태와 에러 본문을 분류기에 주입하고, 호출의 횟수와 순서를 검증하며, 최종 오류에 원래 요청 컨텍스트가 포함되어 있는지 확인하세요.
Claude에서 GPT로의 폴백이 실제로 안전한 경우
모델 패밀리 간 전환은 두 라우트가 동일한 애플리케이션 계약을 만족할 수 있을 때만 안전합니다. 요청과 응답 필드를 정규화하고, 양쪽 모델에서 구조화된 출력 또는 도구 동작을 테스트하며, 필요한 이미지/문서/컨텍스트/추론 기능을 검증한 뒤 라우트를 활성화하세요.
폴백은 부작용도 고려해야 합니다. 첫 번째 라우트가 이미 도구를 호출했거나 데이터를 기록했거나 부분 응답을 스트리밍했다면, 전체 요청을 맹목적으로 반복하는 것은 동작을 중복시키거나 사용자를 혼란스럽게 할 수 있습니다. 체크포인트에서 재개하거나 통제된 실패를 반환하세요.
재시도를 한계 내로 유지하는 운영 점검
- 하나의 총 지연 한도를 설정하세요. 모든 재시도와 폴백 시도를 동일한 데드라인에 포함하세요.
- 재시도를 상한으로 제한하세요. 지터가 있는 백오프를 사용하고 소수의 구성된 한도 이후에는 중단하세요.
- 동시성을 제어하세요. 애플리케이션에서 요청이 나가기 전에 버스트를 줄이세요.
- 서킷 브레이커를 추가하세요. 반복적으로 실패하는 라우트 호출을 일시 중지하세요.
- 의사결정을 로깅하세요. 상태, 에러 코드, 요청 ID, 모델, 시도 횟수, 지연, 폴백 사유를 시크릿 없이 캡처하세요.
- 폴백 비율을 추적하세요. 지속적인 증가는 운영 신호이지, 정상적인 성공 지표가 아닙니다.
자주 묻는 질문
401이 모델 폴백을 유발해야 할 때가 있나요?
아니오. API 키를 수정하거나 다시 로드하세요. 동일한 잘못된 자격 증명으로 호출되는 다른 모델도 같은 이유로 실패합니다.
404가 폴백을 유발해야 하나요?
기본적으로는 아니오. 먼저 기본 URL이나 엔드포인트를 수정하세요. 별도로 검증된 모델 부재 신호만 폴백 분류기에 포함하세요.
429는 몇 번 재시도해야 하나요?
사용자 지연 한도에 맞는 소수의 애플리케이션 한도를 사용하세요. 지터가 있는 백오프와 동시성 감소를 적용하고, 즉시 또는 무한 재시도는 피하세요.
모든 5xx 오류가 재시도 가능한가요?
아니오. 일시적인 500, 503, 504, 524는 재시도 후보이지만, invalid_request를 동반한 500은 페이로드를 수정하기 전까지는 즉시 실패해야 합니다.
Claude와 GPT가 동일한 요청을 변경 없이 사용할 수 있나요?
애플리케이션이 테스트한 공통 필드에 대해서만 가능합니다. 공급자 전용 파라미터, 도구 포맷, 구조화된 출력, 멀티모달 입력은 어댑터가 필요할 수 있습니다. 모델 ID만 바꾸는 것으로 호환성이 보장되지는 않습니다.
전체 폴백 구현은 어디에 있나요?
더 넓은 아키텍처는 How to Build Robust LLM Model Fallback Strategies, 구현 세부는 CometAPI model fallback guide를 참고하세요.
오류 분류기를 게이트키퍼로 삼으세요
자동 폴백은 범위가 좁고 가시적일 때 유용합니다. 인증, 경로, 잘못된 요청 오류는 크게 실패하도록 두세요. 레이트 리밋과 일시적 서버 실패는 백오프로 재시도한 뒤, 재시도 예산이 소진되면 호환 라우트로 이동하세요. 이 정책은 폴백을 구성 버그를 가리는 수단이 아니라 신뢰성 제어 수단으로 바꿉니다.