API 응답 포맷 컨벤션

FE(React) + BE(Spring Boot) 공통 약속
최초 작성: 2026-10-08

---

공통 Envelope

모든 API 응답은 아래 구조를 따른다.

성공

{
  "success": true,
  "data": { }
}

에러

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "이메일은 필수입니다"
  }
}

페이지네이션 목록

{
  "success": true,
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 142,
      "totalPages": 8
    }
  }
}

---

HTTP 상태 코드

코드	상황
200	조회, 수정 성공
201	생성 성공
400	잘못된 요청 (형식 오류)
401	미인증
403	인가 없음
404	리소스 없음
409	현재 리소스 상태와 충돌 (중복, 오래된 수정 제안 등)
422	유효성 검증 실패
413	요청 파일/본문 크기 제한 초과
415	지원하지 않는 미디어 타입
500	서버 내부 오류

---

에러 코드

code	설명
VALIDATION_ERROR	입력값 검증 실패
NOT_FOUND	리소스 없음
UNAUTHORIZED	로그인 필요
FORBIDDEN	권한 없음
DUPLICATE	중복 (이메일 등)
CONFLICT	현재 리소스 상태와 요청이 충돌
PAYLOAD_TOO_LARGE	요청 크기 제한 초과
UNSUPPORTED_MEDIA_TYPE	지원하지 않는 콘텐츠/파일 형식
INTERNAL_ERROR	서버 내부 오류

---

날짜 포맷

ISO 8601 통일

"2026-10-08T14:30:00Z"

---

FE — TypeScript 타입

type ApiResponse<T> =
  | { success: true; data: T }
  | { success: false; error: { code: string; message: string } };

type PaginatedData<T> = {
  items: T[];
  pagination: {
    page: number;
    pageSize: number;
    totalItems: number;
    totalPages: number;
  };
};

위 타입은 frontend/src/types/common.ts에 정의되어 있다.

---

BE — Spring Boot 공통 클래스

BE-Setup 참고

---

변경 이력

날짜	내용	작성자
2026-10-09	API v1의 수정 제안 충돌 및 파일 업로드 오류 코드 추가	Codex
2026-10-08	최초 작성