HTTP 응답 코드 완전 정리 — 개발자가 반드시 알아야 할 상태 코드 가이드

# WebSocket 연결 시 101 응답
GET /chat HTTP/1.1
Upgrade: websocket
Connection: Upgrade

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

# 200 — 조회 성공
GET /api/users/1
→ 200 OK
→ {"id": 1, "name": "김철수", "role": "개발자"}

# 201 — 생성 성공 (Location 헤더에 새 리소스 경로)
POST /api/users
→ 201 Created
→ Location: /api/users/42
→ {"id": 42, "name": "이영희"}

# 202 — 비동기 작업 접수 (이메일 발송, 대용량 처리 등)
POST /api/reports/generate
→ 202 Accepted
→ {"jobId": "abc123", "status": "processing"}

# 204 — 삭제 성공 (본문 없이 응답)
DELETE /api/users/1
→ 204 No Content

# 301 — 영구 이동: 검색 엔진이 새 URL을 인덱싱
# SEO에서 매우 중요. 잘못 쓰면 검색 순위가 사라질 수 있음
HTTP/1.1 301 Moved Permanently
Location: https://new-domain.com/page

# 302 — 임시 이동: 검색 엔진이 기존 URL 유지
# 점검 페이지, 로그인 후 리다이렉트 등
HTTP/1.1 302 Found
Location: /login?redirect=/dashboard

# 1차 요청
GET /api/data
→ 200 OK
→ ETag: "abc123"

# 2차 요청 (브라우저가 ETag를 보냄)
GET /api/data
If-None-Match: "abc123"
→ 304 Not Modified  ← 본문 없이 "캐시 쓰세요" 응답

# 401 — "누구세요?" (인증 실패)
# 로그인하지 않았거나 토큰이 만료됨
GET /api/profile
→ 401 Unauthorized
→ {"error": "토큰이 만료되었습니다. 다시 로그인해주세요."}

# 403 — "당신은 안 됩니다" (인가 실패)
# 로그인은 했지만 해당 리소스에 접근 권한이 없음
GET /api/admin/settings
→ 403 Forbidden
→ {"error": "관리자 권한이 필요합니다."}

# 400 — 요청 자체가 깨짐 (파싱 불가)
POST /api/users
Content-Type: application/json
Body: {invalid json...
→ 400 Bad Request
→ {"error": "JSON 파싱에 실패했습니다."}

# 422 — 형식은 맞지만 내용이 유효하지 않음
POST /api/users
Body: {"email": "not-an-email", "age": -5}
→ 422 Unprocessable Entity
→ {"errors": [
    {"field": "email", "message": "올바른 이메일 형식이 아닙니다"},
    {"field": "age", "message": "0 이상이어야 합니다"}
  ]}

# API 호출 제한 초과
GET /api/search?q=test
→ 429 Too Many Requests
→ Retry-After: 30        ← 30초 후 재시도
→ X-RateLimit-Limit: 100
→ X-RateLimit-Remaining: 0
→ {"error": "요청 제한을 초과했습니다. 30초 후 다시 시도해주세요."}

클라이언트 → [Nginx/ALB] → [애플리케이션 서버] → [DB]
                 │
                 ├── 502: 앱 서버가 죽었거나 잘못된 응답 반환
                 ├── 503: 앱 서버가 점검 중이거나 과부하
                 └── 504: 앱 서버가 응답을 너무 늦게 줌

# 502 — 앱 서버 프로세스가 죽은 경우
→ 502 Bad Gateway
→ Nginx 로그: "upstream prematurely closed connection"

# 503 — 점검 모드 (Retry-After 헤더 포함)
→ 503 Service Unavailable
→ Retry-After: 3600
→ {"error": "서버 점검 중입니다. 1시간 후 다시 시도해주세요."}

# 504 — DB 쿼리가 30초 넘게 걸린 경우
→ 504 Gateway Timeout
→ Nginx 로그: "upstream timed out (110: Connection timed out)"

요청 →  토큰 없음?         → 401 Unauthorized
    →  토큰 만료?          → 401 Unauthorized
    →  토큰 유효, 권한 없음? → 403 Forbidden
    →  토큰 유효, 권한 있음  → 200/201/204...

{
  "status": 422,
  "error": "Unprocessable Entity",
  "message": "입력 데이터가 유효하지 않습니다.",
  "details": [
    { "field": "email", "message": "올바른 이메일 형식이 아닙니다" },
    { "field": "age", "message": "0 이상이어야 합니다" }
  ],
  "timestamp": "2026-04-04T09:30:00Z",
  "path": "/api/users"
}