HTTP 상태 코드: 개발자를 위한 완전 참조 가이드

HTTP 상태 코드는 서버가 클라이언트 요청에 대해 반환하는 세 자리 숫자입니다. 이 완전한 HTTP 상태 코드 참조는 실무에서 만나는 모든 코드를 다룹니다.

HTTP 상태 코드 도구로 즉시 확인 →

1xx — 정보 응답

서버가 요청을 수신하고 처리를 계속하고 있음을 나타냅니다.

2xx — 성공

가장 일반적인 카테고리입니다. 요청이 성공적으로 처리되었습니다.

3xx — 리다이렉션

클라이언트가 추가 작업을 수행해야 합니다.

4xx — 클라이언트 오류

문제가 클라이언트 측에 있습니다.

5xx — 서버 오류

서버가 요청을 처리할 수 없었습니다.

API 상태 코드 모범 사례

적절한 상태 코드로 API를 더 직관적으로 만드세요.

// REST API Status Code Guidelines

// Creating a resource
POST /api/users → 201 Created (with Location header)

// Successful read
GET /api/users/123 → 200 OK

// Successful update
PUT /api/users/123 → 200 OK (with updated resource)
PATCH /api/users/123 → 200 OK

// Successful delete
DELETE /api/users/123 → 204 No Content

// Validation error
POST /api/users (invalid data) → 422 Unprocessable Entity
{
  "error": "Validation failed",
  "details": [
    { "field": "email", "message": "Invalid email format" }
  ]
}

// Authentication required
GET /api/admin → 401 Unauthorized
{ "error": "Authentication required" }

// No permission
GET /api/admin (as regular user) → 403 Forbidden
{ "error": "Insufficient permissions" }

// Resource not found
GET /api/users/999 → 404 Not Found
{ "error": "User not found" }

// Rate limit exceeded
GET /api/search → 429 Too Many Requests
Retry-After: 60
{ "error": "Rate limit exceeded", "retry_after": 60 }

일반적인 디버깅 시나리오

상태 코드는 디버깅의 첫 번째 단서입니다.

CORS Errors (Browser shows "blocked by CORS")

The browser blocks the request, but the actual HTTP status may be hidden. Check server logs. Ensure your server sends the correct Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers headers.

502 Bad Gateway on Deployment

Your reverse proxy (Nginx, Cloudflare) can't reach your application server. Check: Is the app process running? Is it listening on the correct port? Are there firewall rules blocking the connection?

# Check if your app is running
ps aux | grep node

# Check if it's listening on the expected port
netstat -tlnp | grep 3000

# Check Nginx error logs
tail -f /var/log/nginx/error.log

504 Gateway Timeout

The upstream server is too slow. Common causes: slow database queries, external API timeouts, or large file processing. Solutions: optimize queries, add timeouts to external calls, use background jobs for heavy tasks.

429 Rate Limiting

// Implementing exponential backoff in JavaScript
async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url);
    if (response.status !== 429) return response;

    const retryAfter = response.headers.get('Retry-After');
    const delay = retryAfter
      ? parseInt(retryAfter) * 1000
      : Math.pow(2, i) * 1000; // 1s, 2s, 4s

    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error('Max retries exceeded');
}

자주 묻는 질문

401과 403의 차이?

401 = 인증 부족. 403 = 인증되었으나 권한 없음.

200 vs 201 사용 시점?

200은 성공, 201은 새 리소스 생성 시.

418의 의미?

1998년 만우절 농담. 서버가 찻주전자입니다.

SEO에서 301과 302의 차이?

301 = 영구(SEO 전달). 302 = 임시.

429 처리 방법?

Retry-After 헤더 확인, 지수 백오프 구현.

HTTP 상태 코드를 이해하는 것은 기본입니다. 도구를 활용하세요.

HTTP 상태 코드 도구로 확인 →