목록으로

404, 200, 502가 대체 무슨 뜻일까? 쉽게 보는 HTTP 상태 코드 정의집

Kai 2026년 07월 18일 09:06 41 0 2

웹사이트를 만들거나 배포한 뒤 브라우저 개발자 도구를 열어보면 이런 숫자들이 보입니다.

200, 301, 307, 308, 401, 403, 404, 500, 502, 503…

처음 보면 전부 에러 코드처럼 느껴지지만, 사실 그렇지 않습니다.

HTTP 상태 코드는 브라우저가 서버에 요청을 보냈을 때 서버가 돌려주는 처리 결과입니다. 쉽게 말해 서버가 보내는 업무 처리 메모라고 보면 됩니다.

“요청 처리했습니다.”
“주소가 바뀌었습니다.”
“로그인이 필요합니다.”
“그 주소에는 아무것도 없습니다.”
“내부에서 문제가 생겼습니다.”

이런 결과를 숫자 세 자리로 표현한 것이 HTTP 상태 코드입니다.

HTTP 표준은 상태 코드를 첫 번째 숫자에 따라 1xx부터 5xx까지 다섯 종류로 나눕니다. 3xx는 이동 안내, 4xx는 요청을 처리할 수 없는 상황, 5xx는 서버가 요청을 처리하다 실패한 상황입니다.

우선 앞자리만 보면 절반은 이해할 수 있습니다

범위	쉬운 의미	대표 상황
`1xx`	계속 진행 중	요청 일부를 받음
`2xx`	정상 처리	조회·저장·삭제 성공
`3xx`	다른 곳으로 이동	URL 변경, 로그인 이동
`4xx`	요청을 처리할 수 없음	잘못된 주소, 권한 부족
`5xx`	서버 쪽 처리 실패	코드 오류, 서버 장애

중요한 점은 4xx라고 해서 항상 사용자의 잘못은 아니고, 5xx라고 해서 무조건 서버 컴퓨터가 꺼졌다는 뜻도 아니라는 것입니다.

프론트엔드가 잘못된 API 주소를 호출해 404가 발생할 수도 있고, 서버 코드가 외부 API에서 잘못된 응답을 받아 502를 반환할 수도 있습니다.

상태 코드는 정답이 아니라 문제를 찾는 첫 번째 단서입니다.

2xx: 요청이 정상적으로 처리됐습니다

200 OK

무슨 뜻인가요?

가장 일반적인 성공 응답입니다.

서버가 요청을 정상적으로 이해하고 처리했다는 뜻입니다.

언제 보이나요?

게시글 조회 성공
로그인 성공
검색 결과 반환
API 데이터 조회 성공
수정 요청 처리 성공

GET /api/posts
→ 200 OK

무엇을 하면 되나요?

대부분 아무것도 하지 않아도 됩니다.

다만 응답이 200인데 화면에 데이터가 없다면 상태 코드가 아니라 응답 데이터 형식, 프론트엔드 렌더링 또는 조건문을 확인해야 합니다.

200은 “요청을 처리했다”는 뜻이지, 화면이 반드시 의도대로 보인다는 뜻은 아닙니다.

201 Created

무슨 뜻인가요?

요청을 처리한 결과 새로운 데이터나 리소스가 만들어졌다는 뜻입니다.

언제 보이나요?

회원가입 성공
게시글 생성
주문 생성
파일 정보 등록
새로운 프로젝트 생성

POST /api/posts
→ 201 Created

무엇을 하면 되나요?

프론트엔드에서는 생성된 데이터의 ID나 이동할 주소를 확인합니다.

새 게시글을 만들었다면 생성된 게시글 상세 페이지로 이동시키는 식으로 활용할 수 있습니다.

204 No Content

무슨 뜻인가요?

요청은 성공했지만 돌려줄 본문 데이터가 없다는 뜻입니다.

언제 보이나요?

삭제 성공
알림 읽음 처리
저장은 완료됐지만 반환할 데이터가 없음
로그아웃 처리

DELETE /api/posts/10
→ 204 No Content

무엇을 하면 되나요?

204 응답에는 본문이 없으므로 무조건 JSON으로 해석하려 하면 오류가 날 수 있습니다.

// 204인데 이렇게 처리하면 문제가 생길 수 있음
const data = await response.json();

삭제 API가 204를 반환한다면 상태 코드만 확인하고 목록을 새로 불러오거나 화면에서 해당 항목을 제거하면 됩니다.

3xx: 에러가 아니라 이동 안내입니다

301, 302, 307, 308은 대체로 요청한 주소 대신 다른 주소로 이동하라는 의미입니다.

브라우저가 자동으로 이동해버리기 때문에 사용자는 상태 코드를 보지 못할 때도 많습니다.

301 Moved Permanently

무슨 뜻인가요?

해당 주소가 영구적으로 새 주소로 변경됐다는 뜻입니다.

언제 보이나요?

기존 도메인을 새 도메인으로 이전
게시글 URL 구조 영구 변경
www 주소를 대표 도메인으로 통일
오래된 페이지를 새 페이지로 이전

/old-page
→ 301
→ /new-page

무엇을 하면 되나요?

의도한 이동이라면 문제가 아닙니다.

하지만 다음을 확인해야 합니다.

새 주소가 정확한가?
이동이 여러 번 연속으로 발생하지 않는가?
A → B → C처럼 불필요한 이동이 없는가?
무한 리다이렉트가 발생하지 않는가?
내부 링크가 아직 옛날 주소를 가리키고 있지 않은가?

영구적으로 바뀐 주소라면 사이트 내부 링크도 새 주소로 수정하는 것이 좋습니다.

302 Found

무슨 뜻인가요?

현재는 다른 주소로 보내지만, 원래 주소가 영구적으로 바뀐 것은 아닐 수 있다는 의미입니다.

언제 보이나요?

로그인하지 않은 사용자를 로그인 페이지로 이동
임시 이벤트 페이지로 이동
지역이나 언어에 따라 다른 페이지 제공
짧은 기간 동안 다른 화면으로 전환

무엇을 하면 되나요?

임시 이동이 의도된 것인지 확인합니다.

다만 POST 요청 이후 302를 사용할 경우 클라이언트 구현에 따라 다음 요청이 GET으로 바뀌는 동작이 나타날 수 있습니다. 요청 메서드를 반드시 유지해야 한다면 307 또는 308을 검토해야 합니다. RFC 9110은 307과 308에서 리다이렉트 후에도 원래 요청 메서드를 변경하지 않도록 정의합니다.

303 See Other

무슨 뜻인가요?

요청 처리는 끝났고, 결과는 다른 주소를 GET 방식으로 조회하라는 뜻입니다.

언제 보이나요?

폼 제출 후 결과 페이지로 이동
주문 생성 후 주문 완료 페이지로 이동
게시글 작성 후 상세 화면으로 이동

POST /orders
→ 303 See Other
→ GET /orders/123

무엇을 하면 되나요?

폼 제출 후 새로고침으로 같은 요청이 다시 전송되는 문제를 막을 때 유용합니다.

POST → 303 → GET 구조로 만들면 결과 페이지를 새로고침해도 주문이나 글 작성 요청이 반복될 가능성을 줄일 수 있습니다.

304 Not Modified

무슨 뜻인가요?

“이 파일은 지난번 이후 바뀌지 않았으니, 이미 저장된 캐시를 사용하세요”라는 뜻입니다.

언제 보이나요?

이미지 캐시
CSS·자바스크립트 캐시
브라우저가 이전 파일의 변경 여부 확인
ETag 또는 Last-Modified 기반 재검증

무엇을 하면 되나요?

대부분 정상입니다.

304를 보고 파일을 못 불러왔다고 오해할 수 있지만, 실제로는 브라우저가 기존 파일을 재사용하면서 다운로드를 줄인 것입니다.

변경한 CSS나 이미지가 계속 이전 버전으로 보인다면 다음을 확인하세요.

파일 이름에 버전 또는 해시가 붙는가?
CDN 캐시가 남아 있는가?
브라우저 강력 새로고침을 했는가?
배포 결과에 새 파일이 실제 포함됐는가?

307 Temporary Redirect

무슨 뜻인가요?

다른 주소로 임시 이동시키되, 기존 요청 방식을 그대로 유지하라는 뜻입니다.

즉 POST 요청이었다면 이동한 주소에도 POST로 다시 요청합니다.

POST /api/payment
→ 307 Temporary Redirect
→ POST /api/v2/payment

언제 보이나요?

로그인 미들웨어가 다른 경로로 요청을 넘길 때
프레임워크가 URL을 임시로 정규화할 때
HTTP를 HTTPS로 임시 전환할 때
API 엔드포인트를 임시 이전했을 때
서버리스·프록시 계층에서 경로를 변경할 때

무엇을 하면 되나요?

먼저 의도된 이동인지 확인하세요.

브라우저 개발자 도구의 Network 탭에서 다음을 확인하면 됩니다.

최초 요청 주소
응답의 Location 헤더
이동한 최종 주소
요청 메서드가 그대로 유지되는지
같은 두 주소를 반복해서 오가는지

307 자체는 오류가 아닙니다.
문제는 원하지 않는 이동, 반복 이동, 잘못된 목적지입니다.

개발 환경에서는 잘 되는데 배포 후 307이 반복된다면 다음을 의심할 수 있습니다.

로그인 세션이나 쿠키가 저장되지 않음
보호된 경로 설정 오류
HTTP·HTTPS 판별 오류
프록시 헤더 설정 문제
URL 끝의 / 처리 규칙 충돌
미들웨어가 자기 자신으로 다시 이동시킴

308 Permanent Redirect

무슨 뜻인가요?

다른 주소로 영구 이동시키면서 요청 방식도 그대로 유지하라는 뜻입니다.

307의 영구 버전이라고 이해하면 쉽습니다.

POST /api/old
→ 308 Permanent Redirect
→ POST /api/new

언제 보이나요?

API 주소를 영구적으로 이전
도메인 규칙 영구 변경
프레임워크의 trailing slash 처리
HTTP에서 HTTPS로 영구 이동
오래된 엔드포인트를 새 엔드포인트로 통합

무엇을 하면 되나요?

영구 이동이 맞는지 신중하게 확인해야 합니다.

308은 브라우저나 중간 캐시에 기억될 수 있으므로 잘못 설정하면 수정 후에도 이전 리다이렉트가 남아 있는 것처럼 보일 수 있습니다.

확인할 항목은 다음과 같습니다.

임시 변경인데 308을 사용하지 않았는가?
목적지 URL이 정확한가?
요청 메서드와 본문을 유지해도 안전한가?
리다이렉트 루프가 없는가?
CDN이나 브라우저 캐시를 비워야 하는가?

RFC 9110에서 307은 임시, 308은 영구 리다이렉트이며, 두 코드 모두 원래 요청 메서드를 유지합니다.

307과 308의 차이 한 번에 보기

코드	이동 기간	요청 메서드 유지	쉬운 표현
`302`	임시	변경될 수 있음	지금만 이쪽으로
`303`	임시	GET으로 전환	결과는 여기서 조회
`307`	임시	유지	같은 방식으로 잠깐 이쪽
`301`	영구	변경될 수 있음	앞으로 계속 이쪽
`308`	영구	유지	같은 방식으로 앞으로 계속 이쪽

4xx: 요청을 현재 상태로는 처리할 수 없습니다

4xx는 서버가 요청을 받았지만 주소, 인증, 권한, 입력값 등의 이유로 처리할 수 없다는 뜻입니다.

“사용자 잘못”으로만 이해하면 안 됩니다. 프론트엔드 코드가 잘못된 요청을 만들어 보내는 경우도 많습니다.

400 Bad Request

무슨 뜻인가요?

요청 형식이나 내용이 잘못돼 서버가 처리할 수 없다는 뜻입니다.

언제 보이나요?

JSON 문법 오류
필수 값 누락
잘못된 날짜 형식
숫자 자리에 문자열 전달
요청 본문을 읽을 수 없음
잘못된 쿼리 파라미터

{
  "email": "test@example.com",
  "age": "스물다섯"
}

서버가 age에 숫자만 허용하면 400이 발생할 수 있습니다.

무엇을 하면 되나요?

Network 탭에서 Request Payload 확인
Content-Type 확인
필수 필드 확인
JSON 문법 확인
백엔드 검증 규칙 확인
서버가 반환한 오류 메시지 확인

401 Unauthorized

무슨 뜻인가요?

이름 때문에 “권한 없음”으로 오해하기 쉽지만, 실무에서는 보통 인증 정보가 없거나 유효하지 않다는 뜻입니다.

쉽게 말하면 다음과 같습니다.

“누구인지 확인되지 않았습니다. 로그인하거나 유효한 인증 정보를 보내주세요.”

언제 보이나요?

로그인하지 않음
액세스 토큰 누락
토큰 만료
잘못된 API 키
인증 헤더 형식 오류
세션 쿠키가 전달되지 않음

무엇을 하면 되나요?

로그인 상태 확인
Authorization 헤더 확인
토큰 만료 확인
쿠키의 도메인·Secure·SameSite 설정 확인
프론트와 API 도메인이 다르면 쿠키 전송 설정 확인
API 키가 운영 환경변수에 등록됐는지 확인

403 Forbidden

무슨 뜻인가요?

서버가 요청자를 알아봤지만 해당 작업을 할 권한이 없다는 뜻입니다.

쉽게 비교하면 이렇습니다.

401: 누구인지 확인이 안 됨
403: 누구인지는 알지만 허용할 수 없음

언제 보이나요?

일반 사용자가 관리자 페이지 접근
다른 사용자의 문서 삭제 시도
허용되지 않은 IP에서 접속
저장소·파일 권한 부족
보안 정책이나 방화벽에 의해 차단
CORS 또는 플랫폼 접근 정책 문제

무엇을 하면 되나요?

사용자 역할과 권한 확인
서버 측 권한 검사 확인
파일·스토리지 정책 확인
방화벽 또는 CDN 차단 규칙 확인
요청 대상의 소유자 ID 확인
관리자 권한을 프론트에서만 검사하고 있지 않은지 확인

버튼을 숨겼다고 권한 관리가 끝나는 것은 아닙니다.
실제 권한 검사는 반드시 서버에서도 해야 합니다.

404 Not Found

무슨 뜻인가요?

요청한 주소에서 해당 리소스를 찾을 수 없다는 뜻입니다.

가장 유명한 상태 코드지만 원인은 생각보다 다양합니다.

언제 보이나요?

페이지 주소 오타
API 경로 오타
삭제된 게시글
배포되지 않은 정적 파일
대소문자 불일치
동적 라우트 설정 누락
SPA 새로고침 설정 문제
데이터베이스에 해당 ID가 없음

무엇을 하면 되나요?

페이지가 404라면

URL 철자 확인
파일 이름의 대소문자 확인
라우터 경로 확인
동적 파라미터 확인
배포 결과에 페이지가 포함됐는지 확인

API가 404라면

프론트가 호출한 전체 URL 확인
/api/user와 /api/users처럼 경로 차이 확인
HTTP 메서드 확인
운영 환경의 API 기본 주소 확인
해당 데이터가 실제 존재하는지 확인

SPA가 새로고침할 때만 404라면

React·Vue 같은 SPA는 브라우저 내부에서 경로를 처리하지만, 새로고침하면 서버가 해당 파일을 직접 찾으려고 합니다.

이 경우 서버 또는 호스팅에 모든 경로를 index.html로 보내는 rewrite 설정이 필요할 수 있습니다.

404는 “서버 전체가 죽었다”는 뜻이 아닙니다.
서버에는 연결됐지만 요청한 대상을 찾지 못했다는 뜻에 가깝습니다.

405 Method Not Allowed

무슨 뜻인가요?

주소는 존재하지만, 그 주소에서 요청한 HTTP 메서드를 허용하지 않는다는 뜻입니다.

언제 보이나요?

GET /api/posts/10     → 허용
DELETE /api/posts/10  → 허용하지 않음

또는 API가 POST만 받는데 브라우저가 GET으로 호출한 경우입니다.

무엇을 하면 되나요?

GET, POST, PUT, PATCH, DELETE 중 올바른 방식인지 확인
라우트 구현 여부 확인
HTML 폼의 method 확인
리다이렉트 과정에서 메서드가 바뀌지 않았는지 확인
서버 응답의 Allow 헤더 확인

408 Request Timeout

무슨 뜻인가요?

서버가 요청을 기다렸지만 제한 시간 안에 완전한 요청을 받지 못했다는 뜻입니다.

언제 보이나요?

인터넷 연결 불안정
너무 느린 파일 업로드
요청 본문 전송 지연
프록시나 서버의 짧은 제한 시간
연결은 만들었지만 요청을 끝내지 못함

무엇을 하면 되나요?

네트워크 상태 확인
업로드 파일 크기 확인
클라이언트 타임아웃 확인
프록시·웹서버 제한 시간 확인
무조건 반복 재시도하지 말고 재시도 간격 적용

409 Conflict

무슨 뜻인가요?

요청 자체는 이해했지만 현재 데이터 상태와 충돌해 처리할 수 없다는 뜻입니다.

언제 보이나요?

이미 가입된 이메일
중복된 사용자명
동시에 같은 문서를 수정
이미 취소된 주문을 다시 취소
현재 버전과 다른 오래된 데이터로 업데이트

무엇을 하면 되나요?

최신 데이터를 다시 불러오기
중복 여부 확인
사용자에게 충돌 내용을 안내
버전 번호나 수정 시간을 활용한 동시성 제어
요청을 덮어쓸지 취소할지 선택하게 하기

410 Gone

무슨 뜻인가요?

해당 리소스가 과거에는 존재했지만 의도적으로 제거됐으며 돌아오지 않을 가능성이 크다는 뜻입니다.

언제 보이나요?

종료된 이벤트 페이지
영구 삭제된 API
철회된 다운로드 파일
다시 제공하지 않을 콘텐츠

404와 무엇이 다른가요?

404: 있는지 없는지 알 수 없거나 현재 찾을 수 없음
410: 과거에 있었지만 영구적으로 제거됨

무엇을 하면 되나요?

사이트 운영자라면 관련 내부 링크를 제거하고, 대체 페이지가 있다면 적절한 이동을 제공하세요.

413 Content Too Large

무슨 뜻인가요?

요청 데이터나 업로드 파일이 서버가 허용하는 크기보다 크다는 뜻입니다.

언제 보이나요?

대용량 이미지 업로드
동영상 업로드
매우 큰 JSON 전송
서버리스 함수 요청 크기 제한 초과
Nginx·프록시 업로드 제한 초과

무엇을 하면 되나요?

파일 압축
이미지 크기 축소
직접 업로드 대신 스토리지 업로드 URL 사용
웹서버 요청 크기 제한 확인
플랫폼의 최대 업로드 용량 확인
사용자에게 업로드 제한을 미리 표시

415 Unsupported Media Type

무슨 뜻인가요?

서버가 요청 본문의 데이터 형식을 지원하지 않는다는 뜻입니다.

언제 보이나요?

서버는 JSON을 기대하는데 다른 형식으로 보낸 경우입니다.

Content-Type: text/plain

또는 파일 업로드 API에 지원하지 않는 파일 형식을 보낸 경우입니다.

무엇을 하면 되나요?

Content-Type 헤더 확인
JSON이라면 application/json 확인
파일 업로드라면 multipart/form-data 처리 확인
서버가 지원하는 확장자와 MIME 타입 확인

422 Unprocessable Content

무슨 뜻인가요?

요청 형식은 읽을 수 있지만 내용의 의미나 검증 조건 때문에 처리할 수 없다는 뜻입니다.

언제 보이나요?

이메일 형식이 잘못됨
비밀번호 조건 불충족
종료일이 시작일보다 빠름
재고보다 많은 수량 주문
필드 간 논리 조건 불일치

400과 무엇이 다른가요?

실무에서 자주 쓰는 구분은 다음과 같습니다.

400: 요청 형식 자체가 잘못됨
422: 형식은 맞지만 값이 규칙에 맞지 않음

다만 실제 API마다 400과 422의 사용 기준은 다를 수 있으므로 해당 서비스의 API 문서를 확인해야 합니다.

429 Too Many Requests

무슨 뜻인가요?

짧은 시간에 요청을 너무 많이 보내 제한에 걸렸다는 뜻입니다.

RFC 6585는 429를 일정 시간 동안 너무 많은 요청을 보낸 상황에 사용하는 코드로 정의하며, 서버는 Retry-After 헤더로 다시 요청할 시점을 알려줄 수 있습니다.

언제 보이나요?

버튼을 여러 번 연속 클릭
무한 반복 API 호출
AI API 사용량 제한
로그인 시도 횟수 초과
크롤링 속도 제한
무료 요금제 호출 한도 초과

무엇을 하면 되나요?

Retry-After 헤더 확인
즉시 반복 호출하지 않기
지수 백오프 적용
검색창에 debounce 적용
결과 캐시
중복 요청 차단
요금제·사용량 한도 확인

1초 후 재시도
2초 후 재시도
4초 후 재시도
8초 후 재시도

429가 발생했는데 무한 재시도하면 차단을 더 악화시킬 수 있습니다.

5xx: 서버가 요청을 처리하다 실패했습니다

5xx는 요청이 서버까지 도착했지만 서버 또는 그 뒤에 연결된 시스템에서 처리에 실패한 경우입니다.

사용자가 새로고침하면 우연히 해결될 수도 있지만, 운영자는 반드시 로그를 확인해야 합니다.

500 Internal Server Error

무슨 뜻인가요?

서버 내부에서 예상하지 못한 문제가 발생했지만 더 구체적인 상태 코드를 반환하지 못했다는 뜻입니다.

언제 보이나요?

처리되지 않은 예외
환경변수 누락
데이터베이스 연결 실패
존재하지 않는 값을 참조
잘못된 서버 코드
운영 환경에서만 빠진 설정
응답 직렬화 실패

무엇을 하면 되나요?

사용자는 잠시 후 다시 시도할 수 있지만, 개발자는 서버 로그를 확인해야 합니다.

확인 순서는 다음과 같습니다.

오류가 발생한 시간 기록
어떤 URL과 메서드였는지 확인
서버·함수 로그 확인
오류 스택 확인
직전 배포 변경 사항 확인
환경변수와 DB 연결 확인
동일 조건으로 재현

사용자 화면에 스택 트레이스, DB 주소, 비밀키 같은 내부 정보를 그대로 노출하면 안 됩니다.

501 Not Implemented

무슨 뜻인가요?

서버가 해당 요청 방식이나 기능을 지원하지 않는다는 뜻입니다.

언제 보이나요?

서버가 특정 HTTP 메서드를 구현하지 않음
아직 개발되지 않은 기능
프록시가 해당 기능을 지원하지 않음

무엇을 하면 되나요?

API 문서에서 지원 여부 확인
요청 메서드 확인
서버 구현 추가
지원되는 대체 기능 사용

405와 비슷해 보이지만, 405는 해당 리소스에서 그 메서드를 허용하지 않는 경우이고, 501은 서버가 그 기능 자체를 지원하지 않는 상황에 가깝습니다.

502 Bad Gateway

무슨 뜻인가요?

앞단 서버나 프록시가 뒤쪽 서버에 요청을 전달했지만 정상적인 응답을 받지 못했다는 뜻입니다.

구조를 단순하게 보면 다음과 같습니다.

사용자
  ↓
CDN·프록시·로드밸런서
  ↓
애플리케이션 서버

중간 서버는 살아 있지만 애플리케이션 서버에서 잘못된 응답이 오면 502가 발생할 수 있습니다.

언제 보이나요?

애플리케이션 서버가 종료됨
서버가 잘못된 형식으로 응답
프록시 대상 주소 오류
배포 직후 서버가 아직 준비되지 않음
서버리스 함수 실행 실패
외부 업스트림 서비스 장애

무엇을 하면 되나요?

애플리케이션 서버가 실행 중인지 확인
배포 로그 확인
프록시 대상 호스트와 포트 확인
서버 함수 로그 확인
업스트림 서비스 상태 확인
DNS와 TLS 설정 확인

502에서는 브라우저 코드보다 서버와 프록시 사이를 먼저 확인하는 편이 좋습니다.

503 Service Unavailable

무슨 뜻인가요?

서버가 현재 요청을 처리할 수 없는 상태라는 뜻입니다.

대체로 일시적인 장애를 표현합니다.

언제 보이나요?

서버 점검
트래픽 폭증
서버 자원 부족
DB 연결 한도 초과
서버리스 동시 실행 한도 초과
의존 서비스 중단
인스턴스가 아직 준비되지 않음

무엇을 하면 되나요?

운영자는 다음을 확인합니다.

CPU·메모리 사용량
요청 수 증가
DB 연결 수
자동 확장 상태
외부 서비스 상태
배포 직후 준비 상태
헬스 체크 실패 여부

서버는 가능한 경우 Retry-After 헤더를 통해 다시 요청하기 적절한 시점을 전달할 수 있습니다.

클라이언트에서는 즉시 무한 재시도하지 말고 일정 간격을 두고 다시 시도해야 합니다.

504 Gateway Timeout

무슨 뜻인가요?

프록시나 게이트웨이가 뒤쪽 서버의 응답을 기다렸지만 제한 시간 안에 응답을 받지 못했다는 뜻입니다.

502와 무엇이 다른가요?

502: 뒤쪽 서버에서 잘못된 응답을 받음
504: 뒤쪽 서버의 응답을 제시간에 받지 못함

언제 보이나요?

데이터베이스 쿼리가 너무 느림
외부 AI API 응답 지연
대용량 작업을 요청 안에서 처리
서버 간 네트워크 문제
함수 실행 시간 제한 초과
무한 루프 또는 교착 상태
타임아웃 설정이 너무 짧음

무엇을 하면 되나요?

가장 오래 걸리는 작업 측정
DB 느린 쿼리 확인
외부 API 타임아웃 설정
독립 요청 병렬 처리
긴 작업을 큐나 백그라운드 작업으로 분리
불필요한 순차 호출 제거
프록시와 앱 서버의 타임아웃 비교

단순히 제한 시간을 늘리는 것은 임시방편일 수 있습니다. 먼저 어떤 작업에서 시간이 소요되는지 확인하는 것이 중요합니다.

자주 헷갈리는 코드만 다시 비교해보기

401과 403

코드	의미	쉬운 표현
`401`	인증 필요 또는 인증 실패	누구인지 확인이 안 됩니다
`403`	권한 부족	누군지는 알지만 허용할 수 없습니다

404와 410

코드	의미	쉬운 표현
`404`	찾을 수 없음	여기에는 없는 것 같습니다
`410`	영구 제거	있었지만 완전히 삭제했습니다

400과 422

코드	의미	쉬운 표현
`400`	요청 형식이나 내용에 문제	요청을 제대로 읽기 어렵습니다
`422`	읽을 수 있지만 검증 실패	이해했지만 이 값으로 처리할 수 없습니다

500, 502, 503, 504

코드	주로 문제가 생긴 곳	쉬운 의미
`500`	애플리케이션 내부	코드나 설정에서 예상 못 한 오류
`502`	프록시와 뒤쪽 서버 사이	뒤쪽 서버의 응답이 이상함
`503`	서비스 가용성	지금은 처리할 수 없음
`504`	뒤쪽 서버의 응답 시간	기다렸지만 제시간에 안 옴

상태 코드를 발견했을 때 실제 확인 순서

상태 코드만 보고 AI에게 “고쳐줘”라고 요청하기보다 다음 정보를 먼저 모아야 합니다.

1. 어떤 요청에서 발생했는지 확인

브라우저 개발자 도구의 Network 탭에서 빨간색 요청 또는 문제의 요청을 선택합니다.

확인할 내용:

Request URL
Request Method
Status Code
Request Headers
Request Payload
Response Headers
Response Body
요청 소요 시간

2. 최초 응답인지 이동 후 응답인지 확인

최종 화면에 404가 보여도 실제 흐름은 다음과 같을 수 있습니다.

원래 주소
→ 307
→ 로그인 주소
→ 308
→ 다른 주소
→ 404

이 경우 404만 고칠 것이 아니라 첫 번째 리다이렉트부터 추적해야 합니다.

3. 프론트 문제인지 서버 문제인지 구분

요청 자체가 전송되지 않음: 프론트 코드 가능성
요청 URL·메서드가 잘못됨: 프론트 또는 API 연결 설정
400~499: 입력, 인증, 권한, 경로 확인
500: 애플리케이션 로그 확인
502~504: 프록시, 서버, DB, 외부 API 확인

4. 로컬과 배포 환경의 차이를 확인

배포 후에만 발생한다면 다음을 살펴보세요.

환경변수 누락
API 기본 URL 차이
쿠키 도메인·보안 설정
DB 연결 문자열
파일명 대소문자
서버리스 실행 제한
프록시·리라이트 설정
HTTP와 HTTPS 차이

5. AI에게는 이렇게 질문하세요

운영 환경에서 POST /api/orders 요청 시
307 응답 후 /login으로 이동합니다.

확인한 정보:
- 로컬에서는 정상 동작
- 로그인 쿠키는 브라우저에 존재
- 최초 요청 메서드는 POST
- 응답 Location은 /login
- 미들웨어에서 인증을 검사하고 있음

추측으로 전체 코드를 수정하지 말고,
307이 발생하는 조건과 확인해야 할 쿠키·미들웨어 설정을
우선순위대로 설명해주세요.

또는 다음처럼 요청할 수 있습니다.

GET /api/products 요청에서 504가 발생합니다.

확인한 정보:
- 응답 시간 약 10초
- 서버 함수에서 DB 조회와 외부 API를 순차 실행
- 로컬에서는 약 2초
- 배포 플랫폼 함수 제한 시간은 확인하지 못함

병목 후보를 DB, 외부 API, 함수 제한 시간으로 나누고
각 항목을 검증하는 방법부터 제시해주세요.

마지막으로 기억할 핵심

HTTP 상태 코드는 외워야 하는 시험 문제가 아닙니다.

숫자를 보면 다음 질문으로 바꾸면 됩니다.

2xx: 성공했다는데 결과도 올바른가?
3xx: 어디로 이동했고 왜 이동했는가?
4xx: 요청의 주소·인증·권한·입력값 중 무엇이 문제인가?
5xx: 서버, DB, 프록시, 외부 API 중 어디서 실패했는가?

특히 307, 308은 오류가 아니라 이동 응답입니다. 반면 404도 단순히 “페이지 없음”만 뜻하지 않고 잘못된 API 주소, 배포 누락, SPA 라우팅 문제, 존재하지 않는 데이터 등 여러 원인에서 나타날 수 있습니다.

상태 코드만 보지 말고 요청 URL, 메서드, 응답 본문, Location 헤더, 서버 로그를 함께 확인해야 문제를 제대로 찾을 수 있습니다.

저장해두고 개발자 도구에서 낯선 숫자를 만날 때마다 찾아보세요.

여러분이 가장 자주 만난 상태 코드는 404, 500, 502 중 무엇인가요?

HTTP코드, 404, 200, 503, 바이브코딩, 빌드인퍼블릭,

김상모
2026.07.18 09:43

컴맹일 때는 이게 그저 오류인가 보다 싶었습니다. 신경도 안쓸 정도로요. 그냥 껐다 키는 수준.

이제는 어떤 의미인지 알아가고 있네요. 참 신기한 분야입니다. 제가 컴맹인데도 이런 걸 읽고 있다는게 신기합니다. 😅

답글
Kai
2026.07.18 09:46

관심이 갔다는 것 자체가 컴맹이 아니라는 증거입니다^^

답글