에러 처리

QA Note API는 표준 HTTP 상태 코드와 JSON 형식의 에러 응답을 반환합니다.

에러 응답 형식

모든 에러 응답은 다음 형식을 따릅니다.

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

입력 유효성 검사 실패 시 상세 정보가 포함됩니다.

{
  "error": "Invalid input",
  "details": [
    {
      "field": "status",
      "message": "Invalid enum value. Expected 'open' | 'in_progress' | 'blocked' | 'fix_submitted' | 'verified' | 'closed'"
    }
  ]
}

HTTP 상태 코드

일반적인 에러 시나리오

401 Unauthorized

API Key가 누락되었거나 유효하지 않습니다.

# 잘못된 예시 — Authorization 헤더 누락
curl https://qanote.app/api/v1/projects

# 올바른 예시
curl https://qanote.app/api/v1/projects \
  -H "Authorization: Bearer qn_YOUR_API_KEY"

해결 방법:

• Authorization 헤더가 포함되어 있는지 확인합니다
• API Key가 qn_으로 시작하는지 확인합니다
• API Key가 만료되지 않았는지 대시보드에서 확인합니다

403 Forbidden

API Key에 필요한 권한(Scope)이 없습니다.

{
  "error": "Insufficient scope"
}

해결 방법:

• 대시보드에서 API Key의 Scope 설정을 확인합니다
• 이슈 조회: issues:read 필요
• 이슈 수정/코멘트 작성: issues:write 필요
• 프로젝트 조회: projects:read 필요

404 Not Found

요청한 리소스(프로젝트, 이슈 등)가 존재하지 않거나, API Key의 조직에 속하지 않습니다.

{
  "error": "Project not found"
}

해결 방법:

• 프로젝트 ID나 이슈 번호가 올바른지 확인합니다
• 해당 리소스가 API Key의 조직에 속하는지 확인합니다

400 Bad Request

요청 본문의 유효성 검사에 실패했습니다.

{
  "error": "Invalid input",
  "details": [
    {
      "field": "priority",
      "message": "Invalid enum value. Expected 'low' | 'medium' | 'high' | 'critical'"
    }
  ]
}

해결 방법:

• 요청 본문이 올바른 JSON 형식인지 확인합니다
• Content-Type: application/json 헤더가 포함되어 있는지 확인합니다
• 파라미터 값이 허용된 범위 내인지 확인합니다

429 Too Many Requests

API 요청 횟수 제한을 초과했습니다.

해결 방법:

• 잠시 후 다시 시도합니다
• 요청 간격을 두고 재시도하는 로직을 구현합니다
• 불필요한 반복 요청을 줄입니다