메인 콘텐츠로 건너뛰기

에러 응답 형식

모든 에러는 다음 형식으로 반환됩니다:
{
  "success": false,
  "message": "에러 메시지"
}
채팅 API 에러 (OpenAI 호환 형식):
{
  "error": {
    "message": "에러 설명",
    "type": "에러 유형",
    "code": "에러 코드"
  }
}

HTTP 상태 코드

코드의미설명
200OK성공
400Bad Request요청 형식 오류, 필수 필드 누락
401UnauthorizedAPI 키 누락, 유효하지 않은 키, 만료된 키
402Payment Required크레딧 부족
403ForbiddenOpen API 비활성화 테넌트, 스코프 부족, 테넌트 비활성
404Not Found모델을 찾을 수 없음
409Conflict중복 리소스 (동일 이름의 키 등)
429Too Many RequestsRate limit 초과
500Internal Server Error서버 내부 오류
502Bad GatewayRAG 서비스 연결 실패

인증 에러 (401)

// API 키 누락
{
  "success": false,
  "message": "Authorization header with Bearer token is required"
}

// 유효하지 않은 키
{
  "success": false,
  "message": "Invalid or expired API key"
}
해결 방법:
  • Authorization: Bearer {KEY} 헤더가 올바른지 확인
  • 키가 폐기 또는 만료되지 않았는지 확인
  • 테넌트 관리자에게 새 키 발급 요청

권한 에러 (403)

// Open API 비활성화
{
  "success": false,
  "message": "Open API is not enabled for this tenant"
}

// 스코프 부족
{
  "success": false,
  "message": "API key does not have required scope: chat"
}
해결 방법:
  • 어드민에서 해당 테넌트의 Open API 활성화 여부 확인
  • 키의 스코프에 필요한 권한이 포함되어 있는지 확인

크레딧 에러 (402)

{
  "error": {
    "message": "Insufficient credits. Please contact your administrator.",
    "type": "insufficient_credits",
    "code": "payment_required"
  }
}
해결 방법:
  • 어드민에서 테넌트 크레딧 잔액 확인
  • 크레딧 충전 요청

문제 해결 체크리스트

  1. 키가 만료되지 않았는지 확인 (Open API 페이지에서 상태 확인)
  2. 키가 폐기되지 않았는지 확인
  3. 어드민에서 테넌트 Open API가 활성화되어 있는지 확인
  4. Authorization: Bearer 형식이 올바른지 확인 (Bearer 뒤에 공백 필수)
  1. 어드민에서 해당 테넌트에 Open API 타입 모델이 생성되어 있는지 확인
  2. 모델 이름이 정확한지 확인 (대소문자 구분)
  3. 모델이 활성 상태인지 확인
  1. "stream": true가 요청 본문에 포함되어 있는지 확인
  2. 클라이언트가 SSE (Server-Sent Events) 파싱을 지원하는지 확인
  3. Accept: text/event-stream 헤더 추가 시도