Conflict

개요

409 Conflict는 요청이 리소스의 현재 상태와 충돌하여 처리할 수 없음을 나타냅니다. 요청 자체는 형식적으로 유효하지만, 서버의 현재 상태와 양립할 수 없는 변경을 시도할 때 반환됩니다.

대표적으로 두 사용자가 같은 문서를 동시에 수정하다 발생하는 편집 충돌(lost update), 이미 존재하는 값으로 인한 유일성 제약 위반, 버전 불일치가 있습니다.

언제 발생하나

• 여러 클라이언트가 동시에 같은 리소스를 갱신하려다 한쪽의 변경이 다른 쪽을 덮어쓰게 되는 상황에서 반환됩니다.
• 회원 가입 시 이미 등록된 이메일처럼, 유일해야 하는 필드에 중복 값을 넣으려 할 때 발생합니다.

요청 / 응답 예시

PUT /api/docs/7 HTTP/1.1
Host: api.example.com
If-Match: "v3"
Content-Type: application/json

{"title":"Edited"}

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":"conflict","message":"Document was modified by another user","currentVersion":"v5"}

코드로 보기

app.put('/api/docs/:id', (req, res) => {
  const doc = db.get(req.params.id);
  if (req.headers['if-match'] !== doc.etag)
    return res.status(409).json({ error: 'conflict', currentVersion: doc.etag });
  // ...
});

@app.post('/api/users')
def create():
    if db.exists(email=request.json['email']):
        abort(409, 'email already registered')
    return {}, 201

실무 참고

• 필드 값 자체의 검증 실패(형식·필수)는 409가 아니라 422 Unprocessable Content가 더 정확합니다.
• If-Match 같은 사전조건 헤더가 실패하는 경우는 412 Precondition Failed와도 관련되므로, 설계에서 둘의 역할을 명확히 나눠야 합니다.
• 응답 본문에 현재 버전이나 충돌 지점을 함께 담아 주면 클라이언트가 자동 병합·재시도를 구현하기 쉬워집니다.

관련 상태코드

관련 헤더

스펙 근거