Error 상태코드 종류 모음

웹개발/Next.js

튼튼발자 2025. 4. 9. 15:05

728x90

개발하다가 에러 너무 많이 봐서 미쳐버릴 것 같아서 이 글 씀.
나중에 또 같은 거 디버깅하면서 구글링 하기 싫어서, 정리해둔다.
HTTP 상태 코드 중에서 특히 에러 코드(4xx, 5xx) 중심으로.
실제 어떤 상황에서 왜 뜨는지, 어떻게 해결할지 간단하게 적음.

4xx: 클라이언트 잘못 (Client Error)

클라이언트가 뭘 잘못해서 생기는 에러. 주로 프론트에서 API 호출할 때 많이 뜬다.
요청 자체가 틀렸거나, 권한이 없거나, 잘못된 URL 요청 등.

상태코드	의미	설명
400 Bad Request	잘못된 요청	요청 포맷 이상하거나, 필수 값 빠졌거나.
401 Unauthorized	인증 필요	로그인 안 했거나 토큰 누락. Authorization 헤더 빠졌을 확률 높음.
403 Forbidden	접근 금지	권한 있어도 이 리소스는 안 됨. 예: 관리자인데 일반 사용자 페이지 접근 같은 거.
404 Not Found	못 찾음	URL 잘못됐거나, 해당 리소스 없음.
408 Request Timeout	시간 초과	요청 보내고 응답 대기하다 타임아웃. 네트워크 문제거나, 서버가 느림.
409 Conflict	요청 충돌	DB 중복 요청, 예: 이미 존재하는 이메일로 회원가입.
413 Payload Too Large	요청이 너무 큼	업로드 파일 너무 클 때 자주 발생. 서버에서 제한 걸려 있음.
414 URI Too Long	URL이 너무 김	GET 요청에 쿼리 스트링 엄청 붙였을 때 터짐.

이건 클라이언트 잘못이 아님. 서버가 뭔가 제대로 못해서 발생함.
백엔드 로그 꼭 봐야 해결 가능.

상태코드	의미	설명
500 Internal Server Error	서버 내부 에러	진짜 이유 모를 때 뜸. 에러 핸들링 안 돼있거나 예외 터짐.
501 Not Implemented	구현 안 됨	API 스펙은 있지만 서버 쪽에서 아직 구현 안 되어 있음.
502 Bad Gateway	게이트웨이 에러	서버가 다른 서버로 요청했는데 거기서 응답이 이상할 때.
503 Service Unavailable	서버 사용 불가	서버 터졌거나 점검 중. 트래픽 몰려서 과부하도 원인.
504 Gateway Timeout	게이트웨이 타임아웃	서버가 다른 서버에서 응답을 못 받아서 발생. 백엔드 API 지연 가능성 큼.

개발하다가 axios나 fetch로 호출할 때 에러 터지면,
무조건 상태 코드부터 보고 로그 찍어야 함.
특히 API 명세서 맞게 보냈는지, 인증/토큰 들어갔는지 꼭 확인할 것.

728x90