에러 처리
API 에러 코드 및 해결 방법
목차
에러 처리
QA Note API는 표준 HTTP 상태 코드와 JSON 형식의 에러 응답을 반환합니다.
에러 응답 형식
모든 에러 응답은 다음 형식을 따릅니다.
json
{
"error": "에러 메시지"
}
입력 유효성 검사 실패 시 상세 정보가 포함됩니다.
json
{
"error": "Invalid input",
"details": [
{
"field": "status",
"message": "Invalid enum value. Expected 'open' | 'in_progress' | 'resolved' | 'closed'"
}
]
}
HTTP 상태 코드
| 상태 코드 | 설명 |
|---|---|
200 | 요청 성공 |
201 | 리소스 생성 성공 |
400 | 잘못된 요청 (유효성 검사 실패) |
401 | 인증 실패 (API Key 누락 또는 만료) |
403 | 권한 부족 (필요한 Scope 없음) |
404 | 리소스를 찾을 수 없음 |
422 | 처리할 수 없는 요청 |
429 | 요청 횟수 제한 초과 |
500 | 서버 내부 오류 |
일반적인 에러 시나리오
401 Unauthorized
API Key가 누락되었거나 유효하지 않습니다.
bash
# 잘못된 예시 — 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)이 없습니다.
json
{
"error": "Insufficient scope"
}
해결 방법:
- 대시보드에서 API Key의 Scope 설정을 확인합니다
- 이슈 조회:
issues:read필요 - 이슈 수정/코멘트 작성:
issues:write필요 - 프로젝트 조회:
projects:read필요
404 Not Found
요청한 리소스(프로젝트, 이슈 등)가 존재하지 않거나, API Key의 조직에 속하지 않습니다.
json
{
"error": "Project not found"
}
해결 방법:
- 프로젝트 ID나 이슈 번호가 올바른지 확인합니다
- 해당 리소스가 API Key의 조직에 속하는지 확인합니다
400 Bad Request
요청 본문의 유효성 검사에 실패했습니다.
json
{
"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 요청 횟수 제한을 초과했습니다.
해결 방법:
- 잠시 후 다시 시도합니다
- 요청 간격을 두고 재시도하는 로직을 구현합니다
- 불필요한 반복 요청을 줄입니다