​
HTTP 상태 코드

API는 표준 HTTP 상태 코드를 사용합니다.
상태 코드설명
200요청 성공
400잘못된 요청
401인증 실패
403권한 없음
404리소스를 찾을 수 없음
422검증 오류
429요청 한도 초과
500내부 서버 오류
503서비스 이용 불가

​
에러 응답 형식

​
일반 API

{
  "status": {
    "code": "40000",
    "message": "Bad Request"
  }
}
​
status
object
required
에러 상태 정보

​
OpenAI 호환 API

/v1/chat/completions 등 OpenAI 호환 API는 다른 에러 형식을 사용합니다. 
{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
​
error
object
required
에러 정보

​
에러 코드

에러 코드HTTP 상태설명
40000400Bad Request - 잘못된 요청
40100401Unauthorized - 인증 실패
40300403Forbidden - 권한 없음
40400404Not Found - 리소스를 찾을 수 없음
42200422Unprocessable Entity - 검증 오류
42900429Too Many Requests - 요청 한도 초과
50000500Internal Server Error - 서버 내부 오류
50300503Service Unavailable - 서비스 이용 불가

​
일반적인 에러 시나리오

​
401 Unauthorized - 인증 실패

원인:
  • API 키가 누락되었거나 잘못된 형식
  • API 키가 삭제되었거나 만료됨
  • Authorization 헤더 형식이 잘못됨
예시: 
{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
해결 방법:
  • API 키가 Bearer YOUR_API_KEY 형식으로 올바르게 전달되었는지 확인
  • API 키가 유효한지 확인 (웹 인터페이스의 API 키 관리 페이지에서 확인)
  • 키가 삭제되었다면 새로운 API 키를 발급받으세요

​
403 Forbidden - 권한 없음

원인:
  • 배포되지 않은 에이전트에 일반 사용자가 접근 시도
  • 리소스에 대한 접근 권한 없음
예시: 
{
  "error": {
    "message": "Agent not deployed",
    "type": "permission_error",
    "code": "forbidden"
  }
}
해결 방법:
  • 일반 사용자(User 역할)는 배포된 에이전트만 사용 가능
  • 개발자 또는 관리자 권한이 필요한 경우 팀 관리자에게 문의
  • 에이전트 배포 상태 확인

​
429 Too Many Requests - 요청 한도 초과

원인:
  • 단위 시간당 API 호출 한도 초과
예시: 
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}
해결 방법:
  • 잠시 대기 후 재시도 (Exponential backoff 권장)
  • API 호출 빈도 최적화
  • 필요시 관리자에게 한도 증가 요청

​
다음 단계

인증

API 키 인증 방법 알아보기

요청 헤더

필수 HTTP 헤더 확인하기