HTTP 상태 코드 가이드

1xx부터 5xx까지 HTTP Status Code의 원인, 해결법 및 에러 응답 샘플을 탐색합니다.

100

Continue

1xx

클라이언트가 요청 헤더 전송 후 요청 본문을 계속 전송해도 됨을 나타냅니다.

발생 원인Expect: 100-continue 헤더 전송 시 수신 확인
권장 해결 방안클라이언트에서 나머지 HTTP Request Body 전송
101

Switching Protocols

1xx

서버가 클라이언트의 프로토콜 전환 요청을 승인했습니다.

발생 원인웹소켓(WebSocket) 커넥션 업그레이드 요청
권장 해결 방안웹소켓 프로토콜 통신으로 전환
200

OK

2xx

요청이 성공적으로 처리되었습니다.

발생 원인정상적인 HTTP GET/POST/PUT 요청 수신
권장 해결 방안클라이언트에 정상 응답 데이터 반환
201

Created

2xx

새로운 리소스가 성공적으로 생성되었습니다.

발생 원인POST 요청으로 DB 등에 레코드 추가 성공
권장 해결 방안생성된 리소스의 URI 또는 객체 반환
202

Accepted

2xx

요청이 접수되었으나 아직 처리가 완료되지 않았습니다.

발생 원인비동기 배치 작업 또는 큐 메시지 접수
권장 해결 방안작업 ID(Task ID) 또는 상태 조회 URL 반환
204

No Content

2xx

요청이 성공했지만 응답 본문에 반환할 데이터가 없습니다.

발생 원인DELETE 성공 또는 데이터 변경 성공 후 텅 빈 응답
권장 해결 방안HTTP 204 Header만 반환하고 Body 비움
206

Partial Content

2xx

리스타트/스트리밍 등 리소스의 일부 범위만 성공적으로 전달되었습니다.

발생 원인Range 헤더를 사용한 비디오 스트리밍 분할 요청
권장 해결 방안Content-Range 헤더와 함께 부분 바이너리 데이터 반환
301

Moved Permanently

3xx

요청한 리소스의 URI가 영구적으로 이동되었습니다.

발생 원인도메인 이전 또는 URL 구조 변경
권장 해결 방안Location 헤더에 새 URL을 지정하여 301 리다이렉트
302

Found

3xx

요청한 리소스가 임시로 다른 URI로 이동되었습니다.

발생 원인로그인 후 메인 페이지 리다이렉트 등 임시 이동
권장 해결 방안Location 헤더로 클라이언트를 임시 이동시킴
304

Not Modified

3xx

클라이언트 캐시가 최신 상태이므로 재다운로드가 필요 없습니다.

발생 원인If-Modified-Since 또는 ETag 캐시 검증 성공
권장 해결 방안응답 본문 없이 304 상태만 반환하여 캐시 재사용 유도
307

Temporary Redirect

3xx

요청 메서드를 변경하지 않고 임시 리다이렉트합니다.

발생 원인POST 요청 메서드를 유지한 채 임시 URL로 이동
권장 해결 방안동일 HTTP Method(POST 등) 유지하며 새 URL 요청
308

Permanent Redirect

3xx

요청 메서드를 변경하지 않고 영구 리다이렉트합니다.

발생 원인POST 요청 메서드를 유지한 채 영구 URL로 이동
권장 해결 방안동일 HTTP Method 유지하며 새 영구 URL 요청
400

Bad Request

4xx

잘못된 요청 구문 또는 유효하지 않은 데이터입니다.

발생 원인요청 Body 파라미터 누락 또는 포맷 오류
권장 해결 방안클라이언트 요청 JSON/Query 파라미터 검증
표준 응답 JSON 샘플
{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid email parameter"
}
401

Unauthorized

4xx

인증 자격 증명이 누락되었거나 유효하지 않습니다.

발생 원인JWT 토큰 만료 또는 Authorization 헤더 누락
권장 해결 방안로그인 재수행 또는 토큰 갱신 요청
표준 응답 JSON 샘플
{
  "status": 401,
  "error": "Unauthorized",
  "message": "Token expired"
}
403

Forbidden

4xx

서버가 요청을 이해했지만 승인을 거부했습니다.

발생 원인권한이 부족한 사용자 계정 접근 (Role 미달)
권장 해결 방안사용자 계정의 Role/Permission 권한 검토
404

Not Found

4xx

요청한 리소스를 찾을 수 없습니다.

발생 원인잘못된 URL 엔드포인트 또는 존재하지 않는 ID 조회
권장 해결 방안URL 경로 및 DB 데이터 존재 여부 확인
405

Method Not Allowed

4xx

해당 엔드포인트에서 지원하지 않는 HTTP 메서드입니다.

발생 원인GET 전용 API에 POST/DELETE 요청 전송
권장 해결 방안API 사양에 적합한 HTTP Method 사용
408

Request Timeout

4xx

서버가 클라이언트의 전체 요청 입력을 기다리다 타임아웃되었습니다.

발생 원인네트워크 지연 또는 대용량 파일 전송 중단
권장 해결 방안클라이언트 요청 재전송 및 타임아웃 설정 조정
409

Conflict

4xx

서버의 현재 상태와 충돌이 발생했습니다.

발생 원인중복된 이메일 가입 또는 동시 데이터 수정 충돌
권장 해결 방안중복 데이터 검증 및 트랜잭션 동시성 제어
413

Payload Too Large

4xx

요청 크기가 서버의 허용 용량 제한을 초과했습니다.

발생 원인대용량 이미지/파일 업로드 제한 초과
권장 해결 방안서버 파일 업로드 최대 용량(client_max_body_size) 확장
415

Unsupported Media Type

4xx

서버가 지원하지 않는 Content-Type 형식입니다.

발생 원인application/json 대신 text/plain 헤더로 전송
권장 해결 방안Content-Type: application/json 헤더 지정
422

Unprocessable Entity

4xx

요청 포맷은 올바르나 비즈니스 로직 유효성 검증에 실패했습니다.

발생 원인나이 수치가 음수이거나 필수 비즈니스 조건 불충족
권장 해결 방안비즈니스 필드 데이터 유효성 검증
429

Too Many Requests

4xx

정해진 시간 동안 너무 많은 요청을 보냈습니다.

발생 원인Rate Limiting 속도 제한 초과
권장 해결 방안재시도 대기 시간(Retry-After) 후 다시 요청
500

Internal Server Error

5xx

서버 내부 처리 중 예기치 않은 오류가 발생했습니다.

발생 원인NullPointerException, DB 커넥션 고갈 등 예외 발생
권장 해결 방안서버 애플리케이션 에러 로그 확인 및 핫픽스
표준 응답 JSON 샘플
{
  "status": 500,
  "error": "Internal Server Error",
  "message": "Database connection timeout"
}
501

Not Implemented

5xx

서버가 요청을 이행하는 데 필요한 기능을 지원하지 않습니다.

발생 원인아직 개발되지 않은 API 엔드포인트 호출
권장 해결 방안API 기능 구현 완료 후 제공
502

Bad Gateway

5xx

게이트웨이/프록시 서버가 상위 서버로부터 유효하지 않은 응답을 받았습니다.

발생 원인WAS(Spring/Node) 다운 또는 Nginx 프록시 설정 오류
권장 해결 방안백엔드 WAS 프로세스 상태 및 Nginx upstream 설정 점검
503

Service Unavailable

5xx

서버가 과부하 상태이거나 점검 중이어서 요청을 처리할 수 없습니다.

발생 원인서버 점검 중 또는 CPU/메모리 100% 임계치 도달
권장 해결 방안서버 스케일아웃(Scale-out) 또는 점검 완료 대기
504

Gateway Timeout

5xx

게이트웨이/프록시 서버가 상위 서버로부터 응답을 제시간에 받지 못했습니다.

발생 원인백엔드 DB 쿼리 슬로우 락 또는 외부 API 응답 지연
권장 해결 방안백엔드 API 및 데이터베이스 쿼리 속도 최적화