WebGroundwebground.app
정보 & 가이드 · 웹 레퍼런스

HTTP 상태 코드 & 디버깅 레퍼런스

1xx~5xx HTTP 응답 상태 코드의 의미와 실무 API·CDN 디버깅 팁을 코드·키워드로 즉시 검색하세요.

표시 중: 26 개 코드
100

Continue

초기 요청 헤더를 수신했으며 클라이언트가 요청 본문을 전송해도 됩니다.

팁: 대용량 업로드 시 Expect: 100-continue 헤더와 함께 주로 사용됩니다.

101

Switching Protocols

서버가 프로토콜 업그레이드에 동의했습니다 (주로 HTTP → WebSocket).

팁: WebSocket 연결이 멈추면 Upgrade 및 Connection 헤더를 점검하세요.

200

OK

HTTP 요청이 정상적으로 성공했음을 나타내는 표준 응답입니다.

팁: 200인데도 화면이 깨지면 Content-Type과 응답 JSON 구조를 확인하세요.

201

Created

요청이 성공해 하나 이상의 새 리소스가 생성되었습니다.

팁: REST API에서는 보통 Location 헤더에 새 리소스 URL을 담아 반환합니다.

204

No Content

요청이 성공했고 서버가 의도적으로 빈 본문(body)을 반환했습니다.

팁: DELETE나 CORS OPTIONS 응답(204)에는 response.json()을 호출하지 마세요.

206

Partial Content

요청한 바이트 범위(Range)에 해당하는 파일 조각만 전송했습니다.

팁: 동영상 스트리밍 플레이어나 이어받기 다운로드에서 Range 헤더와 함께 쓰입니다.

301

Moved Permanently

리소스가 새 URL로 영구 이동했으며 검색엔진 SEO 평가도 이전됩니다.

팁: 브라우저가 301을 강하게 캐싱하므로 시크릿 창이나 curl -I로 테스트하세요.

302

Found (Temporary Redirect)

리소스가 일시적으로 다른 URL에서 제공되며 기존 URL 인덱싱을 유지합니다.

팁: OAuth 로그인 흐름이나 임시 점검 페이지 라우팅에 자주 사용됩니다.

304

Not Modified

ETag 또는 Last-Modified 기준 캐시된 사본이 여전히 유효합니다.

팁: 정적 자산 대역폭을 절약합니다. 구버전이 남으면 Cache-Control을 점검하세요.

307

Temporary Redirect

원래 HTTP 메서드와 요청 본문을 그대로 유지하는 임시 리다이렉트입니다.

팁: 리다이렉트 후에도 POST 요청을 유지해야 할 때 302 대신 307을 쓰세요.

308

Permanent Redirect

원래 HTTP 메서드와 본문을 그대로 유지하는 영구 리다이렉트입니다.

팁: Next.js trailingSlash 리다이렉트나 HTTPS 정규화에 널리 쓰입니다.

400

Bad Request

잘못된 문법이나 유효하지 않은 파라미터 때문에 요청을 처리할 수 없습니다.

팁: JSON 문법, 필수 쿼리 필드, Content-Type 헤더를 검증하세요.

401

Unauthorized

요청한 엔드포인트에 필요한 인증이 없거나 만료·무효 상태입니다.

팁: Authorization Bearer 토큰 만료 여부, API 키 접두사, 세션 쿠키를 확인하세요.

403

Forbidden

클라이언트 신원은 파악되었으나(또는 정책 차단) 접근 권한이 없습니다.

팁: RBAC 권한, CORS/WAF 규칙, 스토리지 버킷 접근 정책을 확인하세요.

404

Not Found

요청한 경로 또는 리소스를 서버에서 찾을 수 없습니다.

팁: 슬래시(/) 유무, 기본 경로(basePath), DNS 라우팅, 삭제된 ID를 점검하세요.

405

Method Not Allowed

엔드포인트는 존재하지만 사용한 HTTP 메서드(GET/POST 등)를 지원하지 않습니다.

팁: Allow 응답 헤더를 확인해 허용된 HTTP 메서드를 파악하세요.

408

Request Timeout

클라이언트가 요청 전송을 끝내기 전에 서버가 소켓 제한 시간으로 닫았습니다.

팁: 느린 모바일 업로드나 keep-alive 연결 풀 불일치를 확인하세요.

409

Conflict

요청이 대상 리소스의 현재 상태와 충돌합니다.

팁: 중복 이메일 가입이나 낙관적 잠금(ETag) 버전 불일치 시 자주 발생합니다.

413

Content Too Large

요청 페이로드가 서버 또는 리버스 프록시의 최대 크기 제한을 초과했습니다.

팁: 업로드 전 클라이언트에서 이미지를 압축하거나 프록시 용량 제한을 높이세요.

415

Unsupported Media Type

Content-Type 헤더에 지정된 페이로드 형식을 서버가 지원하지 않습니다.

팁: Content-Type이 실제 본문(application/json 등)과 일치하는지 확인하세요.

422

Unprocessable Content

JSON 문법은 올바르지만 필드 값의 의미적 유효성 검사에 실패했습니다.

팁: 잘못된 이메일 형식, 음수 값, 누락된 enum 항목 등 상세 에러를 확인하세요.

429

Too Many Requests

클라이언트가 API 호출 속도 제한(Rate Limit)을 초과했습니다.

팁: Retry-After 헤더를 준수하고 지터를 포함한 지수 백오프로 재시도하세요.

500

Internal Server Error

원본 서버에서 처리되지 않은 예기치 못한 예외가 발생했습니다.

팁: 서버 스택 트레이스, 누락된 환경변수, 데이터베이스 오류 로그를 확인하세요.

502

Bad Gateway

프록시, CDN 또는 로드밸런서가 업스트림 서버로부터 잘못된 응답을 받았습니다.

팁: 업스트림 앱 프로세스가 실행 중이고 올바른 포트를 리스닝하는지 확인하세요.

503

Service Unavailable

서버가 일시적 과부하 상태이거나 정기 점검 중입니다.

팁: Retry-After 헤더, 헬스 체크 실패, 콜드 스타트 고갈 여부를 확인하세요.

504

Gateway Timeout

프록시 또는 CDN이 업스트림 서버 응답을 기다리다 시간 초과되었습니다.

팁: 느린 DB 쿼리를 최적화하거나 오래 걸리는 작업을 비동기 큐로 분리하세요.

지금 400 Bad Request나 API JSON 응답을 디버깅 중이신가요?JSON 포맷터 열기

HTTP 상태 코드 5가지 분류 이해하기

모든 HTTP 응답은 RFC 9110 표준에 따른 3자리 상태 코드로 시작합니다. 첫 번째 숫자만 확인해도 개발자, DevOps 엔지니어, SEO 담당자는 문제의 성격을 즉시 파악할 수 있습니다.

1xx는 프로토콜 전환·정보, 2xx는 요청 성공, 3xx는 캐시·리다이렉션, 4xx는 클라이언트 요청 오류, 5xx는 원본 서버 또는 프록시/업스트림 장애를 의미합니다.

실무에서 자주 헷갈리는 상태 코드 구분

유사한 상태 코드 간의 미묘한 차이를 정확히 알면 디버깅 시간을 크게 줄일 수 있습니다:

  • 401 Unauthorized vs 403 Forbidden: 401은 인증 정보가 없거나 만료된 상태(재로그인 필요), 403은 인증되었거나 정책상 식별되었지만 접근 권한이 거부된 상태입니다.
  • 301/302 vs 307/308: 구형 301/302 리다이렉트는 POST 요청을 GET으로 바꿀 수 있지만, 307과 308은 원래 HTTP 메서드와 본문을 그대로 유지합니다.
  • 502 Bad Gateway vs 504 Gateway Timeout: 502는 업스트림 서버가 잘못된 응답을 보냈을 때, 504는 업스트림 응답을 기다리다 제한 시간이 초과되었을 때 발생합니다.

자주 묻는 질문 (FAQ)

401과 403의 차이는 무엇인가요?+

401 Unauthorized는 인증 토큰이 없거나 만료·오류인 상태이고, 403 Forbidden은 권한(RBAC)이나 보안 정책(WAF/CORS)에 의해 접근 자체가 차단된 상태입니다.

429 Too Many Requests 응답은 어떻게 처리해야 하나요?+

응답의 Retry-After 헤더가 있으면 해당 시간을 대기하고, 없다면 지수 백오프(Exponential Backoff)와 지터(Jitter)를 적용해 재시도하세요.

204 No Content 응답에서 response.json()이 실패하는 이유는 무엇인가요?+

204 응답은 의도적으로 본문(body)이 비어 있으므로 JSON 파싱 시 오류가 발생합니다. 파싱 전 response.status === 204 여부를 먼저 확인하세요.

WebGround의 다른 도구 더 보기

전체 보기