Unprocessable Content

개요

422 Unprocessable Content(옛 이름 Unprocessable Entity)는 요청의 문법(JSON 구조 등)은 올바르지만 담긴 값이 의미상 잘못되어 처리할 수 없다는 뜻입니다. 이메일 형식 오류, 음수 나이, 필수 필드 누락 같은 검증 실패에 사용됩니다.

400 Bad Request가 '요청 자체가 깨졌다'는 신호라면, 422는 '요청은 잘 파싱했지만 내용이 비즈니스 규칙·유효성 검증을 통과하지 못했다'는 더 구체적인 신호입니다. 많은 REST/JSON API가 폼 검증 실패에 이 코드를 씁니다.

언제 발생하나

• JSON은 유효하지만 필드 값이 유효성 검증을 통과하지 못했을 때
• 필수 필드가 비어 있거나 형식(이메일, 날짜, 범위)이 어긋날 때
• 비즈니스 규칙(예: 시작일이 종료일보다 늦음)을 위반했을 때

요청 / 응답 예시

POST /api/signup HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"email":"not-an-email","age":-3}

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{"errors":[{"field":"email","msg":"invalid format"},{"field":"age","msg":"must be >= 0"}]}

코드로 보기

app.post('/api/signup', (req, res) => {
  const errors = validate(req.body);
  if (errors.length) {
    return res.status(422).json({ errors });
  }
  // create the user...
});

@app.post('/api/signup')
def signup():
    data = request.get_json()
    errors = validate(data)
    if errors:
        return jsonify(errors=errors), 422
    # ...

실무 참고

• 일부 팀은 문법·의미 오류를 구분하지 않고 400으로 통일하기도 합니다. 어느 규약을 쓰는지 API 문서로 확인하세요.
• 422는 재시도한다고 저절로 해결되지 않습니다 — 입력을 고쳐야만 통과합니다(반면 429·503은 재시도가 유효).

관련 상태코드

관련 헤더

스펙 근거