error-codes.md

Quespot API 에러 코드

모든 응답은 같은 봉투를 쓴다. 실패 시 isSuccess=false이고 code로 분기한다. HTTP 상태만으로 분기하지 말 것 — 같은 409라도 코드가 다르다.

{
  "isSuccess": false,
  "code": "MISSION_409_011",
  "message": "아직 잠금 해제되지 않은 미션입니다. 이전 미션을 먼저 완료해 주세요.",
  "errorDetail": null
}

errorDetail은 입력 검증 실패(COMMON_400_002)일 때만 { "필드명": "메시지" }로 채워진다.

Swagger의 각 API에는 프론트가 분기 처리해야 하는 도메인 에러만 @ApiResponse로 적혀 있다. 그 외는 이 표를 본다. 코드·메시지의 원본은 각 도메인의 *ErrorCode enum이다.

공통 처리 원칙

상황	처리
AUTH_401_003 (access token 만료·위조)	POST /api/auth/reissue로 재발급 후 원 요청 1회 재시도. 재발급도 AUTH_401_004면 로그아웃
AUTH_401_001 (토큰 없음)	로그인 화면으로
AUTH_403_001	관리자 전용 API. 일반 사용자 화면에서는 나오면 안 됨
COMMON_400_002	errorDetail의 필드별 메시지를 폼에 표시
COMMON_503_001	일시적 장애(DB 접근 실패 등). 재시도 버튼
COMMON_500_001, *_502_*	"잠시 후 다시 시도" 안내

COMMON (GeneralErrorCode)

코드	HTTP	메시지	발생 상황	프론트 처리 제안
COMMON_400_001	400	잘못된 요청입니다.	예약(현재 직접 던지는 곳 없음)	일반 오류 안내
COMMON_400_002	400	입력값 검증에 실패했습니다.	@Valid/@Validated 실패, 파라미터 타입 불일치	errorDetail 필드별 메시지 표시
COMMON_404_001	404	요청한 리소스를 찾을 수 없습니다.	예약	일반 오류 안내
COMMON_405_001	405	지원하지 않는 HTTP 메서드입니다.	잘못된 메서드	개발 중 오류
COMMON_500_001	500	서버 내부 오류가 발생했습니다.	처리되지 않은 예외	재시도 안내
COMMON_503_001	503	서비스를 일시적으로 이용할 수 없습니다.	DB 접근 실패(동시 요청의 UNIQUE 위반 포함), 인증 필터의 저장소 오류	재시도 버튼

AUTH (AuthErrorCode)

코드	HTTP	메시지	발생 상황	프론트 처리 제안
AUTH_400_001	400	이메일 인증이 완료되지 않았습니다.	가입 시 이메일 인증 미완료	인증 코드 확인 화면으로
AUTH_400_002	400	이메일 인증 코드가 올바르지 않거나 만료되었습니다.	인증 코드 확인 실패	재입력, 만료면 재발송 유도
AUTH_400_003	400	비밀번호와 비밀번호 확인이 일치하지 않습니다.	가입 폼	비밀번호 확인 필드 오류 표시
AUTH_400_004	400	지원하지 않는 로그인 방식입니다.	provider 값 오류(연결·해제)	개발 중 오류
AUTH_400_005	400	현재 사용할 수 없는 로그인 방식입니다.	서버 설정에서 꺼진 provider	해당 버튼 숨김
AUTH_400_006	400	허용되지 않은 OAuth2 프론트 리다이렉트 주소입니다.	소셜 로그인 시작 시 redirect 파라미터가 허용 목록 밖	개발 중 오류(환경 설정 확인)
AUTH_401_001	401	인증이 필요합니다.	토큰 없음, 사용자 조회 실패	로그인 화면으로
AUTH_401_002	401	이메일 또는 비밀번호가 올바르지 않습니다.	로그인 실패	폼 오류 표시
AUTH_401_003	401	Access Token이 올바르지 않거나 만료되었습니다.	만료·위조 토큰, 사용자 정보 불일치	reissue 후 재시도
AUTH_401_004	401	Refresh Token이 올바르지 않거나 만료되었습니다.	재발급 실패, 로그아웃된 토큰	로그아웃 처리
AUTH_401_005	401	소셜 로그인에 실패했습니다.	provider 응답 오류, 토큰 암복호화 실패	"소셜 로그인 실패" 안내 후 재시도
AUTH_401_006	401	소셜 로그인 코드가 올바르지 않거나 만료되었습니다.	login/oauth2/exchange의 1회용 코드 재사용·만료	소셜 로그인 처음부터
AUTH_401_007	401	소셜 계정 연결 요청이 올바르지 않거나 만료되었습니다.	계정 연결 흐름의 상태 토큰 불일치·만료	연결 처음부터
AUTH_403_001	403	접근 권한이 없습니다.	ADMIN 전용 API를 일반 사용자가 호출	화면에 노출하지 않음
AUTH_404_001	404	연결된 로그인 방식을 찾을 수 없습니다.	연결되지 않은 provider 해제	연결 목록 새로고침
AUTH_409_001	409	이미 가입된 이메일입니다.	가입, 인증 코드 요청	로그인 유도
AUTH_409_002	409	이미 다른 로그인 방식으로 가입된 이메일입니다. 기존 로그인 방식으로 로그인한 후 마이페이지에서 계정을 연결해주세요.	소셜 로그인 이메일이 기존 이메일 계정과 겹침	기존 방식 로그인 → 마이페이지 연결 안내
AUTH_409_003	409	이미 연결된 로그인 방식입니다.	같은 provider 재연결	연결됨 상태 표시
AUTH_409_004	409	해당 소셜 계정은 다른 사용자에게 연결되어 있습니다.	소셜 계정이 타 계정에 연결됨	다른 소셜 계정 사용 안내
AUTH_409_005	409	마지막 로그인 방식은 연결 해제할 수 없습니다.	유일한 로그인 수단 해제 시도	해제 버튼 비활성
AUTH_429_001	429	이메일 인증 코드 발송 요청이 너무 많습니다. 잠시 후 다시 시도해주세요.	발송 횟수 제한	대기 시간 안내
AUTH_429_002	429	이메일 인증 코드 입력 횟수를 초과했습니다. 인증 코드를 다시 발급해주세요.	확인 시도 제한	재발송 유도
AUTH_502_001	502	소셜 계정 연결 해제에 실패했습니다. 잠시 후 다시 시도해주세요.	provider unlink API 실패	잠시 후 재시도

PROFILE (ProfileErrorCode)

코드	HTTP	메시지	발생 상황	프론트 처리 제안
PROFILE_404_001	404	프로필이 생성되지 않았습니다.	프로필 조회·수정 전 미생성	프로필 생성 화면으로
PROFILE_409_001	409	이미 프로필이 생성되어 있습니다.	프로필 중복 생성	수정 API로 전환

MISSION (MissionErrorCode)

코드	HTTP	메시지	발생 상황	프론트 처리 제안
MISSION_400_001	400	위도와 경도를 올바르게 입력해 주세요.	목록·스팟 조회의 lat/lng 한쪽만, 사진 좌표 한쪽만	좌표를 둘 다 보내거나 둘 다 비움
MISSION_400_002	400	유효하지 않은 미션 조회 커서입니다.	목록·아카이브·스팟 커서 위조·형식 오류	첫 페이지부터 다시
MISSION_400_003	400	해당 코스에 속하지 않는 미션입니다.	시작 시 courseAttemptId의 코스에 없는 미션	courseAttemptId 제거
MISSION_400_004	400	지원하지 않는 지역입니다.	미션 스팟 조회에 서울 외 지역	지역 선택 제한
MISSION_404_001	404	미션 후보를 찾을 수 없습니다.	관리자 후보 검수	관리자 화면
MISSION_404_002	404	검수자 정보를 찾을 수 없습니다.	관리자 후보 검수	관리자 화면
MISSION_404_003	404	미션을 찾을 수 없습니다.	상세·시작·좋아요·코스 anchor의 미션이 없거나 비활성	목록 새로고침
MISSION_404_004	404	미션 시도를 찾을 수 없습니다.	attemptId 없음 또는 타인의 시도	진행 중 목록 재조회
MISSION_404_005	404	미션 코스를 찾을 수 없습니다.	코스 없음·비활성·남의 코스(상세·좋아요·시작)	코스 목록 새로고침
MISSION_404_006	404	코스 진행을 찾을 수 없습니다.	courseAttemptId 없음·타인 것	코스 화면으로
MISSION_404_007	404	행정구역을 찾을 수 없습니다.	스팟 조회의 districtCode 오류	구 선택 UI 갱신
MISSION_409_001	409	대기 중인 미션 후보만 수정하거나 검수할 수 있습니다.	관리자 후보 검수	관리자 화면
MISSION_409_002	409	이미 완료한 미션은 다시 시작할 수 없습니다.	완료한 미션 재시작	완료 표시, 시작 버튼 숨김
MISSION_409_003	409	진행 중인 시도가 아닙니다.	완료·포기된 시도에 포기 요청	상태 재조회
MISSION_409_004	409	이미 종료된 시도입니다. 새로 시작해 주세요.	포기한 시도에 도착 인증	미션 다시 시작 유도
MISSION_409_005	409	이미 사진을 기록했습니다.	미션당 1장 초과	등록 버튼 숨김
MISSION_409_006	409	완료된 미션에만 사진을 기록할 수 있습니다.	완료 전 사진 등록	도착 인증 먼저
MISSION_409_007	409	이미 완주한 코스는 다시 시작할 수 없습니다.	완주 코스 재시작	완주 표시
MISSION_409_008	409	진행 중인 코스가 아닙니다.	완주·포기 코스에 시작·포기	코스 없이 단독 시작
MISSION_409_009	409	이미 시작했거나 완료한 미션은 코스 앵커로 선택할 수 없습니다.	코스 생성 anchor 조건	다른 미션 선택
MISSION_409_010	409	주변에 이어갈 미션이 부족해 코스를 만들 수 없습니다.	코스 생성 실패	"이 근처엔 코스를 만들 수 없어요"
MISSION_409_011	409	아직 잠금 해제되지 않은 미션입니다. 이전 미션을 먼저 완료해 주세요.	코스 앞 미션 미완료 상태에서 시작·좋아요	이전 미션 완료 안내

ITEM (ItemErrorCode)

코드	HTTP	메시지	발생 상황	프론트 처리 제안
ITEM_400_001	400	이미 보유한 아이템입니다.	보유 아이템 재구매	장착 버튼으로 전환
ITEM_404_001	404	보유하지 않은 아이템입니다.	미보유 아이템 장착	구매 유도
ITEM_404_002	404	판매 중인 아이템을 찾을 수 없습니다.	없는·비활성 아이템 구매	상점 새로고침

REWARD (RewardErrorCode)

코드	HTTP	메시지	발생 상황	프론트 처리 제안
REWARD_400_001	400	포인트가 부족합니다.	구매 시 잔액 < 가격(포인트 행이 없는 신규 사용자 포함)	부족 안내 + 잔액 표시

NOTIFICATION (NotificationErrorCode)

코드	HTTP	메시지	발생 상황	프론트 처리 제안
NOTIFICATION_404_001	404	알림을 찾을 수 없습니다.	읽음 처리 대상이 없거나 다른 사용자의 알림	목록 새로고침
NOTIFICATION_500_001	500	FCM 토큰 등록에 실패했습니다.	토큰 저장 실패	다음 앱 실행 때 재등록

TOUR (TourSyncErrorCode)

코드	HTTP	메시지	발생 상황	프론트 처리 제안
TOUR_409_001	409	TourAPI 동기화가 이미 실행 중입니다.	관리자 동기화 중복 실행	관리자 화면

FILE (FileErrorCode)

코드	HTTP	메시지	발생 상황	프론트 처리 제안
FILE_400_001	400	파일명이 올바르지 않습니다.	presigned 발급 시 파일명·확장자 오류	파일 선택 다시
FILE_400_002	400	지원하지 않는 이미지 형식입니다.	이미지 외 content-type	형식 안내
FILE_400_003	400	파일 크기가 올바르지 않습니다.	크기 제한 초과·0	크기 안내
FILE_400_004	400	파일 객체 키가 올바르지 않습니다.	제출한 objectKey 형식 오류	업로드 1단계부터 다시
FILE_400_005	400	잘못된 업로드 경로의 파일입니다.	purpose 디렉터리 불일치(예: missions/ 대신 profiles/)	purpose 맞춰 재발급
FILE_400_006	400	본인이 업로드한 파일만 등록할 수 있습니다.	다른 사용자의 objectKey 제출	재발급
FILE_502_001	502	파일 업로드 URL 생성에 실패했습니다.	스토리지 서명 실패	잠시 후 재시도
FILE_502_002	502	파일 삭제에 실패했습니다.	스토리지 삭제 실패	잠시 후 재시도
FILE_502_003	502	파일 조회 URL 생성에 실패했습니다.	조회 서명 실패	이미지 자리 비움 + 재시도
FILE_503_001	503	파일 저장소가 설정되지 않았습니다.	서버 스토리지 미설정(로컬 등)	개발 환경 확인