HTTP 상태 코드를 제대로 쓰는 법
HTTP 응답 코드는 클라이언트가 서버의 처리 결과를 빠르게 판단하기 위한 약속입니다. 잘 골라 쓰면 API 사용자가 catch 한 줄로 적절한 분기 처리를 할 수 있지만, 200으로 모든 응답을 내려 보내거나 무조건 500을 던지는 API는 디버깅이 어렵고 캐싱·재시도 정책도 제대로 동작하지 않습니다. 이 사전에는 RFC 9110(HTTP Semantics)과 IANA 등록 코드 중 자주 등장하는 약 70개 — 100 Continue, 200 OK, 201 Created, 204 No Content, 301/302/303/307/308, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 410 Gone, 418 I'm a teapot, 422 Unprocessable Entity, 429 Too Many Requests, 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout 등 — 을 담았습니다.
각 코드 카드에는 한국어 의미, 언제 써야 하는지, 잘못 쓰면 발생하는 문제, 관련 헤더(Location, WWW-Authenticate, Retry-After 등)를 정리해 두었습니다. 코드 번호를 그대로 입력해 검색하거나, "인증", "리다이렉트", "캐시" 같은 한국어 키워드로도 찾을 수 있습니다. 카드를 클릭하면 상세 사용 예시가 펼쳐집니다.
REST API 설계 시 자주 헷갈리는 코드
401과 403은 가장 자주 혼동되는 짝입니다. 401은 "인증되지 않음"이라 인증 헤더(WWW-Authenticate)를 첨부해 어떤 인증 방식이 필요한지 알려 줘야 하고, 403은 "인증은 됐지만 권한이 없음"입니다. 302 vs 303 vs 307도 자주 틀립니다. 302는 GET으로 바꿔도 되는지 정의가 모호하니, "임시 리다이렉트 + 메서드 보존"은 307, "임시 리다이렉트 + 강제 GET"은 303, 영구 이동은 301(POST→GET 변경 허용) 또는 308(메서드 보존)을 권장합니다.
자주 묻는 질문 (FAQ)
Q. 422 Unprocessable Entity는 400과 어떻게 다른가요?
A. 400은 요청 형식 자체가 깨진 경우(잘못된 JSON, 누락된 헤더 등), 422는 형식은 맞지만 의미적으로 처리할 수 없는 경우(이메일 형식 오류, 도메인 규칙 위반)에 사용합니다. RFC 4918 WebDAV에서 도입되었고 현재 REST API에서 표준적으로 사용됩니다.
Q. 429 Too Many Requests와 503은 어떻게 다른가요?
A. 429는 "이 클라이언트가 너무 많이 요청"한 경우(레이트 리미트), 503은 "서버가 일시적으로 사용 불가"(점검·과부하)입니다. 둘 다 Retry-After 헤더로 다시 시도해도 되는 시각을 알려 주는 게 표준입니다.
Q. 204 No Content는 언제 쓰나요?
A. 처리는 성공했지만 응답 본문이 없을 때 사용합니다. DELETE 성공 후, PUT으로 자원을 갱신했지만 새 표현을 내려 줄 필요가 없을 때, OPTIONS 응답에 자주 사용됩니다. 본문이 있다면 클라이언트가 무시할 권한이 있습니다.