HTTP 상태 코드 완벽 가이드｜일반적인 오류 원인 및 해결 방법
API를 개발하다가 422가 반환되었습니다. 프로덕션에서 갑자기 502가 나타나기 시작했습니다. 리다이렉트가 301인지 302인지에 따라 SEO 영향이 바뀝니다. HTTP 상태 코드는 웹 개발의 공용 언어이며, 이를 올바르게 이해하는 것이 문제 해결의 첫 단계입니다.
스테이터스 코드의 5 가지 카테고리
| 레인지 | 카테고리 | 의미 |
|---|---|---|
| 1xx | Informational | 요청 수신 및 처리 중 |
| 2xx | Success | 요청 성공 |
| 3xx | Redirection | 추가 작업 필요 (리다이렉트) |
| 4xx | Client Error | 클라이언트 측 문제 |
| 5xx | Server Error | 서버 측의 문제 |
개발자가 가장 자주 만나는 코드
200 OK — 성공
가장 기본적인 성공 응답입니다. API가 예상대로 작동하고 있습니다.
301 Moved Permanently — 영구 리다이렉트
URL이 영구적으로 변경되는 경우에 사용합니다. <strong>SEO 관점에서 기존 URL의 평가가 새 URL로 인계되므로</strong> 사이트 이전 및 HTTPS화에 필수입니다. Google은 301을 「시그널 전달」로 처리합니다.
<strong>흔한 문제</strong>: 301을 의도했는데 302를 반환하는 경우. Apache의 <code>Redirect</code>는 기본값이 302. <code>Redirect 301</code>로 명시.
302 Found — 임시 리다이렉트
임시 리다이렉트. A/B 테스트나 유지보수 중 우회에 사용됨. SEO 평가는 전달되지 않음.
304 Not Modified — 캐시 유효
브라우저가 <code>If-Modified-Since</code> 또는 <code>If-None-Match</code> 헤더로 조건부 요청을 보낸 결과 리소스가 변경되지 않았을 때 반환됩니다. <strong>본문이 전송되지 않으므로</strong> 대역폭을 절약할 수 있습니다.
400 Bad Request — 잘못된 요청
서버가 요청을 분석할 수 없습니다. 원인: 잘못된 JSON, 필수 매개변수 누락, Content-Type 불일치.
# よくあるミス: Content-Type を指定していない
curl -X POST https://api.example.com/users -d '{"name":"Alice"}'
# → 400 (Content-Type: application/json が必要)
# 正しい
curl -X POST https://api.example.com/users \
-H 'Content-Type: application/json' \
-d '{"name":"Alice"}'401 Unauthorized — 인증 필요
인증 정보가 없거나 유효하지 않습니다. Bearer 토큰의 만료, API Key 오류 등입니다.
403 Forbidden — 접근 거부
인증은 통과했지만 권한이 없습니다. 일반 사용자가 관리자 전용 엔드포인트에 접근한 경우 등입니다. 401과의 차이는 「인증 유무」vs「권한 유무」입니다.
404 Not Found — 리소스 없음
가장 유명한 오류입니다. URL 오타, 삭제된 페이지, 라우팅 설정 오류로 인해 발생합니다. SEO 측면에서 「의도적으로 삭제함」을 나타내기 위해 <code>410 Gone</code>을 사용하는 것이 바람직한 경우도 있습니다.
413 Payload Too Large — 크기 초과
파일 업로드에서 자주 나타납니다. Nginx의 <code>client_max_body_size</code> (기본값 1MB), PHP의 <code>upload_max_filesize</code>, API Gateway 제한을 확인하세요.
422 Unprocessable Entity — 유효성 검사 에러
JSON 구문은 올바르지만 비즈니스 로직상 유효하지 않음 (잘못된 이메일 형식, 필수 필드가 비어 있음 등). REST API의 유효성 검사 오류는 이것을 반환하는 것이 일반적입니다.
429 Too Many Requests — 속도 제한
짧은 시간에 너무 많은 요청을 보냈습니다. <code>Retry-After</code> 헤더에 대기할 초 단위 시간이 표시됩니다. 대책: 지수 백오프 (exponential backoff)를 구현합니다.
500 Internal Server Error — 서버 내부 에러
처리되지 않은 예외, NULL 참조, 설정 파일 오류. <strong>가장 위험한 오류</strong>. 서버 로그를 반드시 확인하세요.
502 Bad Gateway — 업스트림 서버 이상
리버스 프록시 (Nginx)가 업스트림 PHP-FPM / Node.js / Python WSGI에 연결하지 못했거나 잘못된 응답을 받았습니다. 업스트림 프로세스 재시작, 메모리 부족, 소켓 연결 타임아웃을 확인하십시오.
503 Service Unavailable — 서비스 일시 중단
유지 관리 중이거나 과부하 상태. <code>Retry-After</code> 헤더를 포함하여 클라이언트에 대기를 알립니다.
504 Gateway Timeout — 업스트림 타임아웃
업스트림 서버가 시간 내에 응답하지 않았음. 무거운 DB 쿼리, 외부 API 지연. Nginx의 <code>proxy_read_timeout</code>을 확인하세요.
DevLab 상태 코드 검색 도구
<a href="/ja/tools/http-status/">HTTP 상태 코드 검색 도구</a>에서는 코드 번호나 키워드 (예: "redirect", "forbidden", "timeout")로 즉시 검색할 수 있으며, 각 코드의 의미・원인・대처법을 목록에서 확인할 수 있습니다. 브라우저에서 완결되며 등록이 필요 없습니다.
관련 도구: <a href="/ja/check/headers/">HTTP 헤더 검증</a>, <a href="/ja/check/redirect-chain/">리다이렉트 체인 추적</a>, <a href="/ja/check/security/">보안 진단</a>.
요약
HTTP 상태 코드는 서버와 클라이언트의 공통 언어입니다. 특히 301 vs 302의 SEO 영향, 400 vs 422의 검증 구분, 5xx의 인프라 진단은 빈출 지식입니다. 막히면 먼저 상태 코드를 확인하고 위의 대처법을 적용하세요.