오류 코드 및 오류 처리

18. 오류 코드 및 오류 처리#

엔드포인트에서 오류가 발생하면 OpenAI 호환 오류 구조가 반환됩니다(/v1/messages 엔드포인트는 Anthropic 형식의 오류 구조 반환):

JSON

{
  "error": {
    "message": "错误描述",
    "type": "invalid_request_error",
    "code": 400
  }
}

상태 코드	의미	문제 해결 방법
`400`	요청 파라미터 누락 또는 잘못됨	`model`, `messages`, `input` 등 필수 필드 확인; `/v1/messages`에는 tools / 멀티모달을 전송하지 마세요
`401`	API 키 누락 또는 무효	`Authorization: Bearer sk-...`가 올바른지, 키가 만료 / 폐기되지 않았는지 확인
`402`	쿼터 소진 또는 잔액 부족	콘솔에서 충전하거나 키의 쿼터를 조정
`403`	출발 IP가 허용 목록에 없음	키의 IP 허용 목록 설정 확인
`404`	모델이 존재하지 않거나 접근 권한 없음 / 작업이 존재하지 않음	`GET /v1/models`로 사용 가능 모델 확인; 경로가 단일 `/v1`인지 확인
`429`	요청 제한 발생	동시성을 낮추고 지수 백오프 후 재시도
`500`	게이트웨이 내부 오류	잠시 후 재시도; 지속되면 지원팀 문의
`502`	업스트림 벤더에서 오류 반환	잠시 후 재시도하거나 모델 교체
`503`	사용 가능한 채널 없음	해당 모델에 당장 사용 가능한 업스트림이 없습니다. 잠시 후 재시도하거나 지원팀 문의