HTTP 상태 코드 빠른 참조
API와 CDN에서 자주 보는 코드 위주입니다. 드문 실험 코드는 제외했습니다.
| 코드 | 이름 | 의미 |
|---|---|---|
| 200 | OK | 본문 포함 성공 |
| 201 | 생성됨 | 리소스 생성됨 |
| 204 | 콘텐츠 없음 | 성공, 빈 본문 |
| 301 | 영구 이동 | 영구 리디렉션 |
| 302 | 찾음 | 임시 리디렉션 |
| 304 | 수정 안 됨 | 캐시 사본 사용 |
| 400 | 잘못된 요청 | 클라이언트 요청이 잘못됨 |
| 401 | 인증 필요 | 인증 필요 또는 실패 |
| 403 | 금지됨 | 인증됐지만 거부됨 |
| 404 | 찾을 수 없음 | 해당 리소스 없음 |
| 405 | 허용되지 않는 메서드 | 잘못된 HTTP 메서드 |
| 408 | 요청 시간 초과 | 클라이언트가 너무 느림 |
| 409 | 충돌 | 상태 충돌 |
| 410 | 사라짐 | 영구 삭제됨 |
| 422 | 처리할 수 없는 개체 | 의미가 잘못됨 |
| 429 | 요청 과다 | 요청 한도 초과 |
| 500 | 내부 서버 오류 | 서버 오류 |
| 502 | 잘못된 게이트웨이 | 업스트림 응답이 잘못됨 |
| 503 | 서비스 이용 불가 | 과부하 또는 중단 |
| 504 | 게이트웨이 시간 초과 | 업스트림 시간 초과 |
참고
- 401과 403: 인증 실패/없음 vs 로그인됐지만 권한 없음.
- 오리진에 닿지 못하면 CDN이 5xx를 줄 수 있습니다.
상태 코드의 다섯 클래스
첫 번째 숫자는 누가 책임지고 대략 무슨 일이 있었는지 알려줍니다. 1xx는 정보성으로 클라이언트가 거의 보지 않습니다. 2xx는 성공을 의미합니다 — 본문이 있는 200 OK, 없는 204 No Content, 부분 다운로드용 206. 3xx는 리소스가 다른 곳에 있다는 뜻이고, 4xx는 요청 자체에 문제가 있다는 뜻입니다. 잘못된 구문, 누락된 자격 증명 또는 속도 제한이 포함됩니다. 5xx는 요청이 정상이었음에도 서버가 실패했다는 뜻입니다. 첫 번째 숫자만 읽어도 클라이언트를 고쳐야 할지 서버 쪽으로 escalation해야 할지 알 수 있습니다.
적절한 리다이렉트 선택하기
301과 308은 모두 영구적인 이동을, 302와 307은 모두 임시 이동을 의미합니다. 차이는 메서드를 어떻게 다루느냐에 있습니다. 301과 302는 역사적으로 클라이언트가 POST를 GET으로 바꿀 수 있게 했지만, 307과 308은 원래 메서드와 본문을 보존합니다. 이는 API와 양식 제출에서 중요합니다. URL이 정말로 완전히 이동했을 때는 301을 사용하고, 유지보수 페이지나 A/B 테스트 같은 임시 라우팅에는 302나 307을 사용하세요. 체인에 주의하세요. 추가로 거치는 모든 hop마다 지연 시간과 링크 평가가 소모되므로 최종 대상으로 바로 리다이렉트해야 합니다.
4xx 오류 정리하기
401은 인증이 누락되었거나 실패했음을 의미하므로 유효한 자격 증명을 전송하면 해결됩니다. 403은 요청을 이해했고 인증도 됐지만 허용되지 않음을 의미하며, 동일한 자격 증명으로 재시도해도 소용없습니다. 404는 리소스가 존재하지 않음을, 410은 존재했다가 의도적으로 제거되었음을 알립니다. 429는 속도 제한에 도달했으므로 백오프해야 하며, Retry-After 헤더를 준수해야 합니다. 400은 일반적으로 잘못된 입력을, 405는 해당 URL에 대해 잘못된 메서드를, 422는 구문은 유효했으나 콘텐츠가 검증에 실패했음을 의미합니다.
5xx 코드 읽기
500은 일반적인 내부 오류입니다. 502 Bad Gateway는 상위 서버가 사용할 수 없는 응답을 반환했음을 의미하고, 503은 서비스가 일시적으로 이용 불가하거나 과부하 상태임을, 504는 상위 서버가 시간 초과되었음을 알립니다. 이들은 서버의 문제이지 호출자의 문제가 아니므로, 해결책은 백오프와 함께 재시도하거나, 상위 서버 상태를 확인하거나, 부하를 줄이는 것입니다. CDN은 도달할 수 없는 원본 대신 502, 503 또는 504를 emit할 수 있으므로, 동일한 오류가 전혀 다른 두 장소에서 올 수 있습니다. server 및 cache-status 헤더를 확인해 어느 쪽인지 파악하세요.
실제 상황에서의 상태 코드: API와 캐싱
일상적으로 두 가지 용법이 주목할 만합니다. 첫째, 캐싱: Cache-Control 헤더와 함께 오는 200은 저장할 수 있고, 304 Not Modified는 클라이언트에 사본을 재사용하라고 알리며, 5xx는 캐시해서는 안 됩니다. 둘째, API: 리소스를 생성하는 POST는 Location 헤더와 함께 201을 반환해야 하고, DELETE는 종종 204를 반환하며, 변경사항이 없는 PATCH는 200이나 204를 반환할 수 있습니다. 예의 바른 클라이언트는 먼저 클래스(2xx, 4xx, 5xx)로 분기한 뒤 정확한 코드로 구분하므로, 재시도 및 백오프 로직이 간단하고 예측 가능합니다.
자주 묻는 질문
- HTTP 403은 무슨 뜻인가요?
- 403은 서버가 요청을 이해하고 인증했지만 해당 리소스 접근을 거부했다는 의미입니다. 401과 달리 다시 로그인해도 해결되지 않습니다.
- HTTP 301과 302 리다이렉트의 차이는 무엇인가요?
- 301은 영구 이동을 뜻하며 클라이언트와 검색 엔진은 이후 새 URL을 사용해야 합니다. 302는 임시 리다이렉트로 원래 URL이 유효합니다.
- HTTP 429는 무슨 뜻이고 어떻게 해결하나요?
- 429는 요청이 너무 많아 속도 제한에 걸렸다는 뜻입니다. 요청 빈도를 줄이고 서버가 반환하는 Retry-After 헤더를 따르세요.