홈 / 문서 / 오류

오류

게이트웨이가 반환하는 모든 상태 코드와 실제 발생 원인 및 해결 방법.

오류는 JSON을 반환하며, 다음을 포함합니다: type 및 사람이 읽을 수 있는 message. 상태 코드는 Anthropic 및 OpenAI의 규칙을 따릅니다.

{"type": "error", "error": {"type": "authentication_error", "message": "invalid api key"}}

상태 코드

코드의미가장 흔한 실제 원인해결 방법
400잘못된 요청누락된 max_tokens Messages에서 누락되었거나 형식이 잘못된 messages 배열본문을 다음과 대조하여 확인하세요: 메시지
401인증되지 않음해당 형식에 맞지 않는 헤더로 키를 전송함x-api-key Messages에는 해당 헤더를, Chat Completions에는 Bearer를 사용하세요
402결제 필요잔액 소진 또는 요금제 만료충전 또는 요금제 구매
403접근 금지키가 폐기되었거나 계정에서 모델이 활성화되지 않음새 키를 생성하고 다음을 확인하세요: /v1/models
404찾을 수 없음기본 URL 오류 — 대개 다음이 중복되거나 누락됨: /v1참고: 기본 URL
429요청 속도 제한동시 요청이 너무 많음대기 시간을 지수적으로 늘려 재시도하세요. 참고: 요청 속도 제한
500게이트웨이 오류예기치 않은 내부 오류한 번 재시도하세요. 문제가 지속되면 요청 ID와 함께 지원팀에 문의하세요
529업스트림 과부하계정이 아닌 공급자의 처리 용량 문제대기 시간을 늘려 재시도하세요. 보통 몇 초 안에 해소됩니다

오류 유형

유형의미
invalid_request_error본문 형식이 잘못되었거나 필수 필드가 누락됨
authentication_error키가 누락되었거나 형식이 잘못되었거나 폐기됨
permission_error키는 유효하지만 해당 모델을 사용할 권한이 없음
not_found_error알 수 없는 경로 또는 모델 ID
rate_limit_error요청 제한됨
api_error내부 오류
overloaded_error업스트림 처리 용량 소진

올바른 재시도 방법

재시도 429, 500, 502, 503 및 529. 무작정 재시도하지 마세요: 400, 401, 402 또는 403 — 동일한 요청은 똑같이 실패하며, 응답이 일부 생성된 경우에는 비용이 이중으로 청구될 수 있습니다.

import time, httpx

def call(body, key, tries=4):
    for i in range(tries):
        r = httpx.post(class="s">"https://aiprimetech.io/v1/messages", json=body, timeout=120,
                       headers={class="s">"x-api-key": key,
                                class="s">"anthropic-version": class="s">"2023-06-01"})
        if r.status_code in (429, 500, 502, 503, 529):
            time.sleep(2 ** i)          class=class="s">"c"># 1s, 2s, 4s, 8s
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError(class="s">"upstream unavailable after retries")
프로덕션 환경에서는 대기 시간에 무작위 변동을 추가하세요. 많은 워커가 동시에 재시도하면 일시적인 장애가 동일한 업스트림으로 요청이 한꺼번에 몰리는 현상으로 이어집니다.