Skip to content

API Response Convention

Jump to bottom
유선우 edited this page Oct 9, 2026 · 2 revisions

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 최초 작성

Clone this wiki locally