트러블슈팅 · 에러 코드

16.0 표준 에러 응답 스키마

모든 도구는 공통 에러 응답 모델 ErrorResponse를 사용한다. 정식 스키마는 /openapi.json components.schemas.ErrorResponse에서 직접 확인.

{
  "error": {
    "code": "invalid_token",
    "message": "Access token expired",
    "details": { },
    "request_id": "req_..."
  }
}

HTTP	`error.code` (enum)	의미
401	`invalid_token`	access_token 만료·서명 불일치·발급 폐기
401	`tenant_inactive`	테넌트 비활성 상태
403	`insufficient_scope`	토큰 scope가 도구 요구 권한 미포함 (`rag:read` / `rag:write`)
403	`permission_denied`	RBAC — 사용자가 해당 노드에 접근 권한 없음
404	`not_found`	도구가 참조하는 리소스 (`document`, `entity`, `section`) 미존재
422	`validation_failed`	Pydantic 입력 검증 실패 (필드 누락·타입·enum 위반)
422	`unsupported_format`	인입 파일 포맷 미지원
413	`file_too_large`	인입 파일 200MB 초과
429	`rate_limit_exceeded`	테넌트 / 사용자 단위 호출 한도 초과
500	`rag_indexing_failed`	인입 파이프라인 내부 오류
500	`rag_query_failed`	검색 단계 내부 오류

호스트 측 클라이언트는 error.code 기준으로 분기 처리하고, error.request_id를 운영팀 문의 시 함께 첨부한다.

원인	확인
`access_token` 만료	토큰 엔드포인트 (`/api/v1/user/auth/token`) 재호출
`client_secret` 오류 / 폐기됨	AX Flow 콘솔에서 client credential 상태 확인
`Authorization: Bearer ...` 헤더 누락·오타	헤더 형식 정확? `Bearer <access_token>`
`scope` 부족	토큰 발급 시 요청한 `scope`가 도구 요구 권한 (`rag:read` / `rag:write`)을 포함하는지
테넌트 비활성	AX Flow 콘솔에서 도입사 테넌트 상태 확인

원인	확인·대응
해당 도메인 문서 미인입	`get_indexed_file` / `get_rag_status`로 인입 여부 확인
`filter_metadata`가 너무 좁음	필터 제거 후 재호출
`top_k`가 너무 작음	기본값 10으로 복원
권한 차단 — RBAC	사용자가 해당 노드 권한 보유 여부 확인 (`team`/`private` 노드)
인입 직후 (그래프 추출 미완)	`get_rag_status` `status=done` 확인

정상 — mode="smart" 호출 시 청크 재정렬 점수 미채움. 청크별 점수가 필요하면 mode="deep"으로 호출.