오류
게이트웨이가 반환하는 모든 상태 코드와 실제 발생 원인 및 해결 방법.
오류는 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")
프로덕션 환경에서는 대기 시간에 무작위 변동을 추가하세요. 많은 워커가 동시에 재시도하면 일시적인 장애가 동일한 업스트림으로 요청이 한꺼번에 몰리는 현상으로 이어집니다.