에러

실패 응답은 success: false와 error 객체를 포함합니다.

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "human-readable 설명"
  }
}

details는 일부 에러(INSUFFICIENT_SCOPE·RATE_LIMIT_EXCEEDED)에만 포함되며, 그 외에는 키가 생략됩니다. 각 코드의 details 필드는 아래 표를 참고하세요.

에러 코드

HTTP	code	발생 조건	대응
401	`MISSING_TOKEN`	`Authorization` 헤더 없음	헤더 추가
401	`INVALID_TOKEN`	형식 오류·미존재·폐기·만료 (보안상 통합)	토큰 확인, 만료면 재발급
403	`INSUFFICIENT_SCOPE`	필요한 scope 없음 (`details.required_scope` 참고)	해당 scope를 포함해 재발급
403	`PAT_INCOMPATIBLE_ENDPOINT`	Public API에 노출되지 않은 경로 호출	엔드포인트 카탈로그 확인
404	`NOT_FOUND`	리소스 없음	path의 id 확인
429	`RATE_LIMIT_EXCEEDED`	요청 한도 초과 (`details.scope`로 버킷 구분)	`Retry-After` 만큼 대기
400	`INVALID_QUERY`	잘못된 쿼리 파라미터·cursor 만료·시간 윈도우 초과	메시지 참고 후 보정
400	`INVALID_INPUT`	path 파라미터 형식 오류 (예: UUID가 아닌 `{id}`)	path의 id 형식 수정
500	`INTERNAL`	서버 내부 오류	jitter backoff로 재시도