🔍 API 개발에서의 Conflict(409)와 중복 데이터 처리 개념 정리
API를 개발하다 보면 리소스 생성(Create) 시 중복 데이터 처리에 대한 고민이 자주 발생합니다. 이때 자주 등장하는 HTTP 상태 코드가 바로 409 Conflict입니다. 이 글에서는 409 Conflict의 의미와, 중복 처리와 관련된 개념들을 정리합니다.
✅ 1. 409 Conflict란?
409 Conflict는 클라이언트의 요청이 서버의 현재 상태와 충돌할 때 사용하는 HTTP 상태 코드입니다.
예시 상황:
- 사용자가 이미 존재하는 이메일 주소로 가입 시도
- 동일한 **프로젝트명(title)**으로 중복 생성 시도
POST /projects
{
"title": "AI 리서치"
}- 서버에 이미 같은 이름의 프로젝트가 존재하는 경우 →
409 Conflict
✅ 2. 유니크 제약 조건 (Uniqueness Constraint)
유니크 제약 조건이란, 특정 필드의 값이 시스템 내에서 중복되면 안 되는 규칙입니다.
보통 아래와 같은 필드에 적용됩니다:
- 사용자 이메일 (
email) - 리소스 ID (
id) - 프로젝트명 (
title) 등
처리 방식:
- 서버 또는 데이터베이스에서 유니크 제약 설정
- 중복 시 409 상태 코드와 함께 의미 있는 메시지를 반환
✅ 3. 에러 이름은 명확하게
단순히 ConflictError 같은 일반화된 이름보다는 구체적인 에러명이 더 좋습니다.
비교:
| 일반적인 이름 | 명확한 이름 |
|---|---|
ConflictError | DuplicateProjectNameError |
ValidationError | EmailAlreadyExistsError |
에러의 원인을 구체적으로 표현하면 디버깅과 클라이언트 처리 모두 쉬워집니다.
✅ 4. 중복이 허용되지 않는 조건은 명확히 정의하자
중복 제한은 비즈니스 규칙입니다. 시스템 설계 전에 반드시 확인해야 합니다.
예시 질문들:
- 프로젝트명은 같은 사용자 내에서만 유니크해야 하나요? 전체 시스템에서 유니크해야 하나요?
- 삭제된 데이터는 유니크 검사에 포함되나요?
- 초안(Draft) 상태에서는 중복 허용되나요?
이처럼 유니크 여부는 상황에 따라 달라지므로, 도메인 요구사항 확인이 필수입니다.
✅ 5. 코드 리뷰 시 커뮤니케이션 포인트
- 중복 처리 여부는 시스템이 아닌 비즈니스 판단일 수 있습니다
- 에러 클래스 네이밍은 공통성과 명확성의 균형이 필요합니다
- 리뷰 피드백 반영 시, “어떤 결정이 있었는지” 간단한 설명을 댓글로 남기면 좋습니다
✅ 마무리
409 Conflict는 중복뿐만 아니라 다양한 충돌 상황에 사용될 수 있습니다- 유니크 체크 로직은 단순 구현보다 도메인 규칙에 대한 합의가 우선
- 명확한 에러 네이밍과 충돌 처리 기준 정립은 API 품질을 높이는 핵심입니다
AI/ML Engineer