REST API 설계 시 꼭 알아야 할 HTTP 상태 코드 완벽 정리

RFC 9110에 의해 규정된 HTTP 상태 코드는 클라이언트, 리버스 프록시, CDN, 오리진 서버 간의 약속된 신호 체계입니다. RESTful API 설계에서 상태 코드는 단순한 성공/실패 여부를 넘어, 해당 작업이 캐시 가능한지, 재시도(Retry)가 안전한지, 인증 재갱신이 필요한지를 전달합니다.

모든 에러를 200 OK로 감싸서 바디에 에러 메시지를 넣는 안티 패턴은 프론트엔드 인터셉터 처리와 CDN 캐시 계층을 무력화시키고 모니터링 시스템을 마비시킵니다.

• 1xx (정보형): 요청을 받았으며 작업을 계속 진행 중임을 알림 (예: WebSocket 핸드셰이크 시 101 Switching Protocols).
• 2xx (성공): 클라이언트의 요청이 서버에 성공적으로 도달하여 처리됨 (200 OK, 리소스 생성 시 201 Created, 응답 바디가 없을 때 204 No Content).
• 3xx (리다이렉션): 요청을 완료하기 위해 클라이언트가 추가 조치(새로운 URL 이동 등)를 취해야 함.
• 4xx (클라이언트 오류): 잘못된 파라미터, 권한 부족 등 클라이언트 측의 문제로 요청을 수행할 수 없음.
• 5xx (서버 오류): 유효한 요청임에도 불구하고 서버의 처리 장애나 백엔드 인프라 다운으로 처리에 실패함.

1. 401 Unauthorized vs 403 Forbidden:
   • 401 Unauthorized: "인증되지 않음(Unauthenticated)"을 의미합니다. 토큰이 없거나 만료된 상태이며, 응답에 WWW-Authenticate 헤더를 포함해야 합니다.
   • 403 Forbidden: 사용자의 신원은 확인되었으나 해당 리소스에 접근할 권한(Permission)이 없음을 뜻합니다. 동일한 자격 증명으로 다시 시도해도 결과는 같습니다.
2. 404 Not Found vs 410 Gone:
   • 404 Not Found: 리소스가 현재 URI에 없음. 검색 엔진 크롤러는 일시적 부재일 수 있으므로 추후 다시 방문합니다.
   • 410 Gone: 리소스가 의도적으로 영구 삭제되었음을 명시합니다. 검색 엔진 크롤러는 통상적으로 404보다 410 URL을 색인 데이터베이스에서 더 빠르게 정리합니다.
3. 301 Moved Permanently vs 308 Permanent Redirect:
   • 과거 일부 브라우저는 301 리다이렉트를 따를 때 원래의 POST 메서드를 GET 메서드로 임의 변경하는 동작이 있었습니다.
   • 308 Permanent Redirect는 리다이렉트 후에도 원래의 HTTP 메서드와 바디가 변하지 않음을 보장합니다.

RFC 7807을 대체하여 2023년 승인된 RFC 9457은 application/problem+json 미디어 타입을 통해 표준화된 에러 JSON 스키마를 정의합니다:

{
  "type": "https://api.devutils.run/errors/insufficient-balance",
  "title": "보유 크레딧이 부족합니다.",
  "status": 403,
  "detail": "현재 잔여 크레딧은 30이지만, 해당 작업은 50 크레딧이 필요합니다.",
  "instance": "/account/12345/transactions/abc"
}

• 안전한 메서드(Safe) (GET, HEAD, OPTIONS): 서버의 리소스 상태를 변경하지 않는 읽기 전용 작업.
• 멱등한 메서드(Idempotent) (GET, PUT, DELETE, HEAD): 동일한 요청을 한 번 실행하든 여러 번 실행하든 서버의 상태가 동일하게 유지됨.
• 비멱등한 메서드(Non-Idempotent) (POST, PATCH): 두 번 호출하면 중복 결제가 발생하거나 중복 데이터가 생성될 수 있음.

네트워크 일시 장애로 클라이언트가 재시도 로직을 수행할 때는 반드시 멱등성이 보장된 요청에 대해서만 재시도를 수행해야 합니다.