1. 공통 규칙

1.1 기본 정보

항목 내용
Content-Type application/json; charset=UTF-8
인증 헤더 Authorization: Bearer {accessToken}
날짜 형식 ISO 8601 UTC
JSON 필드명 camelCase
회원 식별자 Java Integer, PostgreSQL INTEGER
대량 증가 식별자 Java Long, PostgreSQL BIGINT
삭제 방식 별도 명시가 없으면 소프트 삭제

모든 이미지 URL은 DB에 저장된 URL이 아니라 MinIO Object Key를 기반으로 요청 시 생성한 단기 Presigned GET URL이다.

1.2 인증 구분

구분 설명
Public 인증 없이 호출 가능
Optional 인증 없이 호출 가능하지만 로그인 시 관계 상태 등을 추가 계산
User ACTIVE 회원 Access Token 필요
Artist ACTIVE 상태의 ARTIST 회원만 호출 가능

1.3 성공 응답

{
  "data": {}
}

단순 상태 변경:

{
  "data":true
}

목록이 비어 있는 경우:

{
  "data": []
}

현재 v1의 정상 업무 응답은 생성·수정·삭제를 포함해 HTTP 200 OK로 통일한다.

1.4 실패 응답

{
  "timestamp":"2026-08-01T10:00:00Z",
  "status":400,
  "code":"VALIDATION_ERROR",
  "message":"입력값 검증에 실패했습니다.",
  "errors": [
    {
      "field":"nickname",
      "rejectedValue":"a!",
      "reason":"닉네임 형식이 올바르지 않습니다."
    }
  ]
}

errors는 필드 검증 실패 시에만 제공한다.

1.5 주요 오류 코드

HTTP 코드 설명
400 INVALID_REQUEST 요청 형식, 타입 또는 파라미터 오류
400 VALIDATION_ERROR 필드 제약 위반
400 INVALID_CURSOR 커서 형식 오류 또는 위·변조
400 INVALID_FILE 파일명·확장자·메타데이터 오류
400 INVALID_OAUTH_PROVIDER 지원하지 않는 OAuth 제공자
401 UNAUTHORIZED 인증 필요
401 INVALID_TOKEN 토큰 형식 또는 서명 오류
401 TOKEN_EXPIRED 토큰 만료
401 OAUTH_AUTHENTICATION_FAILED OAuth 인증 실패
403 FORBIDDEN 권한 또는 소유권 부족
403 ACCOUNT_SUSPENDED 정지 계정
403 ACCOUNT_BANNED 강퇴 계정
403 ACCOUNT_WITHDRAWN 탈퇴 계정
404 RESOURCE_NOT_FOUND 리소스를 찾을 수 없음
404 USER_NOT_FOUND 회원을 찾을 수 없음
404 ARTIST_NOT_FOUND 인증 타투이스트를 찾을 수 없음
404 IMAGE_NOT_FOUND 이미지를 찾을 수 없음
404 TATTOO_NOT_FOUND 타투를 찾을 수 없음
404 POST_NOT_FOUND 게시글을 찾을 수 없음
404 COMMENT_NOT_FOUND 댓글을 찾을 수 없음
404 DM_ROOM_NOT_FOUND 참여 중인 DM방을 찾을 수 없음
404 UPLOAD_OBJECT_NOT_FOUND 업로드 객체를 찾을 수 없음
409 DUPLICATE_RESOURCE 중복 리소스
409 DUPLICATE_NICKNAME 닉네임 중복
409 DUPLICATE_PHONE_NUMBER 휴대폰 번호 중복
409 STATE_CONFLICT 현재 상태에서 처리 불가
413 FILE_TOO_LARGE 파일 크기 초과
415 UNSUPPORTED_MEDIA_TYPE 지원하지 않는 Content-Type
422 NOT_TATTOO_IMAGE 정상 이미지이지만 타투 이미지가 아님
429 RATE_LIMITED 호출 제한 초과
500 INTERNAL_SERVER_ERROR 서버 내부 오류
502 UPSTREAM_SERVICE_ERROR OAuth·AI 모델 서버 오류
503 SERVICE_UNAVAILABLE Redis·MinIO 등 필수 인프라 장애
504 PROCESSING_TIMEOUT 외부 서버 처리 시간 초과

1.6 커서 페이지 응답