HTTP 상태 코드의 의미

브라우저가 페이지를 불러오거나 앱이 API를 호출할 때마다, 서버는 세 자리 상태 코드로 답합니다. 대부분은 볼 일이 없지만, 뭔가 깨졌을 때 — 404, 500 — 그 숫자가 첫 단서입니다. 이 가이드는 상태 코드를 한눈에 읽는 법을 가르쳐 드립니다.

첫 자리를 읽으세요

요령은 첫 자리가 분류를 알려준다는 것이라, 한 번도 본 적 없는 코드의 의도도 이해할 수 있습니다:

• 1xx — 정보(Informational): 받았고, 아직 처리 중(일상 사용에선 드묾).
• 2xx — 성공(Success): 잘 됐음.
• 3xx — 리다이렉션(Redirection): 리소스가 다른 곳에 있음.
• 4xx — 클라이언트 오류(Client error): 요청이 잘못됨(당신 쪽).
• 5xx — 서버 오류(Server error): 요청은 멀쩡했는데 서버가 실패함.

이 4xx 대 5xx 구분이 디버깅할 때 가장 유용한 구별입니다: 4xx는 요청을 고치라는 뜻, 5xx는 서버 탓이라는 뜻.

실제로 만나게 될 코드들

성공과 리다이렉트

• 200 OK — 표준 “잘 됐음” 응답.
• 201 Created — 새 리소스가 생성됨(POST 이후).
• 301 Moved Permanently — 이 URL이 영구히 이동함. 링크를 갱신하세요. SEO에 중요.
• 302 Found — 임시 리다이렉트. 원래 URL을 계속 쓰세요.
• 304 Not Modified — 캐시된 사본이 아직 유효해, 아무것도 다시 보내지 않음.

클라이언트 오류 (4xx)

• 400 Bad Request — 요청 형식이 잘못됨.
• 401 Unauthorized — 인증이 필요함(로그인).
• 403 Forbidden — 인증은 됐지만 허용되지 않음.
• 404 Not Found — 리소스가 존재하지 않음.
• 429 Too Many Requests — 레이트 리밋에 걸림. 속도를 늦추세요.

서버 오류 (5xx)

• 500 Internal Server Error — 일반적인 서버 측 실패.
• 502 Bad Gateway — 상위 서버가 잘못된 응답을 반환함.
• 503 Service Unavailable — 서버가 과부하거나 점검으로 다운됨.
• 504 Gateway Timeout — 상위 서버가 제때 응답하지 않음.

401 vs. 403: 흔한 혼동

이 둘은 비슷하게 느껴지지만 한 단어에서 다릅니다. 401 Unauthorized는 사실 “인증되지 않음(unauthenticated)”을 뜻합니다 — 서버가 당신이 누구인지 모르니 로그인하세요. 403 Forbidden은 서버가 당신이 누구인지 알지만 여전히 허용하지 않는다는 뜻입니다. 하나는 신원에 관한 것, 다른 하나는 권한에 관한 것입니다.

전체 목록

등록된 모든 코드와 그 의미를 — 검색 가능하고 클래스별로 묶어 — 보려면 완전한 HTTP 상태 코드 레퍼런스를 보세요. API 응답을 디버깅 중이라면, JWT와 URL 인코딩 가이드가 당신이 끊임없이 마주칠 다른 두 가지를 다룹니다.