에러 코드

GenD API의 공통 에러 응답 형식 및 주요 에러 코드를 설명합니다.

에러 응답 형식

모든 에러는 다음 JSON 형식으로 반환됩니다:

{
  "detail": "에러 메시지"
}

공통 HTTP 에러 코드

코드	이름	설명
400	Bad Request	잘못된 요청 파라미터, 필수 필드 누락, 유효성 검사 실패
401	Unauthorized	JWT 토큰 누락 또는 만료
403	Forbidden	권한 부족 (관리자 전용 엔드포인트, SqlGuard 차단 등)
404	Not Found	요청한 리소스를 찾을 수 없음
409	Conflict	리소스 중복 (동일 이름의 커넥터, 정책 등)
422	Unprocessable Entity	Pydantic 검증 실패 (타입 불일치, 범위 초과 등)
500	Internal Server Error	서버 내부 오류

422 Validation Error 상세

Pydantic v2 검증 실패 시 상세 오류 정보를 반환합니다:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

외부 서비스 에러

서비스	주요 에러
Trino	쿼리 실행 실패, 연결 타임아웃
OpenSearch	감사 로그 검색 실패
Superset	BI 대시보드 조회 실패
JupyterHub	노트북 서버 관리 실패
Debezium	CDC 커넥터 관리 실패
Dagster	파이프라인 실행 실패
Presidio	PII 마스킹 실패

에러 처리 패턴

모든 라우터는 try/except + logger.error + HTTPException 패턴으로 에러를 처리합니다. 외부 서비스 장애 시 적절한 HTTP 상태 코드와 함께 에러 메시지를 반환합니다.