HTTP 상태 코드 목록
웹 개발에서 자주 마주치는 HTTP 상태 코드를 분류별로 정리했습니다. API 설계, 디버깅, 에러 처리 구현에 활용하세요.
HTTP 상태 코드란
HTTP 상태 코드는 클라이언트(브라우저나 API 클라이언트)의 요청에 대해 서버가 반환하는 응답 상태를 나타내는 세 자리 숫자입니다. 첫 자리로 카테고리가 정해지며 1xx~5xx의 다섯 클래스로 나뉩니다. 적절한 상태 코드를 반환하는 것은 RESTful API 설계에서 매우 중요합니다.
1xx: 정보 응답(Informational)
요청을 받았고 처리를 계속 중임을 나타냅니다. 보통 브라우저가 자동으로 처리하므로 개발자가 직접 다루는 일은 드뭅니다.
| 코드 | 명칭 | 설명 |
|---|---|---|
100 | Continue | 요청의 첫 부분을 받았으며 클라이언트는 요청을 계속할 수 있음 |
101 | Switching Protocols | 프로토콜 전환 요청 수락. WebSocket 연결 시 사용 |
103 | Early Hints | 최종 응답 전에 리소스 프리로드를 시작하기 위한 힌트 |
2xx: 성공 응답(Success)
요청이 정상적으로 수락·처리되었음을 나타냅니다. API 개발에서 가장 자주 사용하는 카테고리입니다.
| 코드 | 명칭 | 설명 | 주요 용도 |
|---|---|---|---|
200 | OK | 요청 성공 | GET / PUT / PATCH 성공 시 |
201 | Created | 요청 성공, 새 리소스가 생성됨 | POST로 리소스 생성 성공 시 |
202 | Accepted | 요청은 수락했으나 처리는 완료되지 않음 | 비동기 처리 접수 시 |
204 | No Content | 요청 성공, 반환할 콘텐츠 없음 | DELETE 성공 시, PUT으로 갱신만 하는 경우 |
206 | Partial Content | 범위 요청에 대한 부분 응답 | 대용량 파일 다운로드 재개 시 |
3xx: 리디렉션(Redirection)
요청을 완료하려면 리디렉션 대상 접근 등 추가 동작이 필요함을 나타냅니다. SEO와 URL 이전 시 중요합니다.
| 코드 | 명칭 | 설명 | 주요 용도 |
|---|---|---|---|
301 | Moved Permanently | 리소스가 영구적으로 이동함 | URL 변경, 도메인 이전. SEO 평가를 승계 |
302 | Found | 일시적으로 다른 URL로 리디렉트 | 점검 중 일시 전송 |
303 | See Other | GET 메서드로 다른 URL 참조 | POST 처리 후 리디렉트(PRG 패턴) |
304 | Not Modified | 리소스가 변경되지 않음 | 브라우저 캐시 활용. 대역폭 절약 |
307 | Temporary Redirect | 일시적 리디렉트(메서드 유지) | HTTP→HTTPS 일시 전송 |
308 | Permanent Redirect | 영구적 리디렉트(메서드 유지) | API 엔드포인트의 영구 이전 |
4xx: 클라이언트 에러(Client Error)
클라이언트 측에 문제가 있음을 나타냅니다. 요청 내용이나 인증 정보의 불비가 원인입니다.
| 코드 | 명칭 | 설명 | 주요 용도 |
|---|---|---|---|
400 | Bad Request | 요청 구문이 올바르지 않음 | 검증 오류, 잘못된 JSON |
401 | Unauthorized | 인증이 필요함 | 미로그인, 토큰 만료 |
403 | Forbidden | 접근 권한이 없음 | 인증되었으나 리소스에 접근 불가 |
404 | Not Found | 리소스를 찾을 수 없음 | 존재하지 않는 URL, 삭제된 리소스 |
405 | Method Not Allowed | 허용되지 않은 HTTP 메서드 | GET 전용 엔드포인트에 POST 전송 |
408 | Request Timeout | 요청이 타임아웃됨 | 클라이언트의 데이터 전송이 느린 경우 |
409 | Conflict | 리소스 충돌 | 중복 데이터 등록, 낙관적 잠금 충돌 |
413 | Payload Too Large | 요청 본문이 너무 큼 | 파일 업로드 상한 초과 |
415 | Unsupported Media Type | 지원하지 않는 미디어 타입 | 잘못된 Content-Type |
422 | Unprocessable Entity | 구문은 올바르나 의미상 처리 불가 | 검증 오류(상세) |
429 | Too Many Requests | 레이트 리밋 초과 | API 호출 횟수 제한 |
5xx: 서버 에러(Server Error)
서버 측에서 처리에 실패했음을 나타냅니다. 서버 설정 불비나 애플리케이션 버그가 원인입니다.
| 코드 | 명칭 | 설명 | 주요 용도 |
|---|---|---|---|
500 | Internal Server Error | 서버 내부 오류 | 처리되지 않은 예외, 애플리케이션 버그 |
501 | Not Implemented | 서버가 지원하지 않는 기능 | 미구현 API 엔드포인트 |
502 | Bad Gateway | 게이트웨이가 잘못된 응답을 수신 | 리버스 프록시의 업스트림 서버가 응답 불가 |
503 | Service Unavailable | 서비스 이용 불가 | 점검 중, 과부하 상태 |
504 | Gateway Timeout | 게이트웨이 타임아웃 | 업스트림 서버로부터의 응답이 타임아웃 |
자주 묻는 질문
401과 403의 차이는?
401 Unauthorized는 인증이 필요함을 나타내며 로그인이나 토큰 제공을 요구합니다. 403 Forbidden은 인증은 되었으나 리소스에 대한 접근 권한이 없음을 나타냅니다. 예를 들어 일반 사용자가 관리자 전용 페이지에 접근한 경우에는 403이 적절합니다.
301과 308의 차이는?
둘 다 영구 리디렉트이지만 301은 리디렉트 과정에서 HTTP 메서드가 GET으로 바뀔 수 있습니다. 308은 요청 메서드를 유지한 채 전달합니다. POST 요청의 리디렉트 대상에서도 POST를 유지하고 싶다면 308을 사용하세요.
413 에러가 나면?
파일 업로드 시 413 Payload Too Large가 반환된 경우에는 서버(Nginx: client_max_body_size, Apache: LimitRequestBody)와 PHP(upload_max_filesize, post_max_size) 설정을 모두 확인하세요. DevLab의 임계값 테스트 파일로 실제 상한을 검증할 수 있습니다.