HTTP 상태코드와 에러 핸들링

HTTP란?

HTTP(Hypertext Transfer Protocol)는 웹 서버와 웹 클라이언트가 데이터를 주고받기 위해 사용하는 통신 프로토콜입니다.
TCP/IP 위에서 동작하며, HTML, XML뿐 아니라 이미지, 음성, 동영상, JavaScript, PDF 등 다양한 데이터를 전송할 수 있습니다.

클라이언트(예: 브라우저)가 서버에 HTTP 요청 메시지를 보내면, 서버는 요청을 처리한 후 HTTP 응답 메시지로 결과를 반환합니다.
이때 응답 메시지의 상태 라인에 포함된 상태 코드(status code)를 통해 요청의 처리 결과를 알 수 있습니다.

 

HTTP 상태 코드란?

HTTP 상태 코드는 서버가 클라이언트의 요청을 어떻게 처리했는지 알려주는 3자리 숫자입니다.
첫 번째 숫자는 응답의 범주를, 나머지 두 자리는 세부 의미를 나타냅니다.

 

상태 코드의 분류

범위	분류	설명
1XX	정보(Informational)	요청을 받았으며, 처리를 계속 진행하라는 의미
2XX	성공(Success)	요청을 성공적으로 처리함
3XX	리다이렉션(Redirection)	추가 동작(다른 URL로 이동 등)이 필요함
4XX	클라이언트 에러(Client Error)	잘못된 요청 등 클라이언트 측 문제
5XX	서버 에러(Server Error)	서버 내부의 문제로 요청 처리 실패

 

프론트엔드에서 자주 사용하는 주요 HTTP 상태 코드

코드	의미	설명
200	OK	요청이 성공적으로 처리됨
204	No Content	요청은 성공했으나 응답 본문이 없음
401	Unauthorized	인증이 필요하거나 토큰이 만료됨
403	Forbidden	권한이 없어서 접근이 금지됨
404	Not Found	요청한 리소스를 찾을 수 없음
500	Internal Server Error	서버 내부 오류로 요청 처리 실패

• 200: 정상 처리. 프론트엔드에서는 .success에서 처리.
• 204: 본문 없는 성공 응답. 데이터 바인딩이 필요 없는 경우 별도 처리 필요.
• 401: 인증 토큰 만료 등 권한 없음. 보통 토큰 재발급 로직과 연계.
• 403: 권한 없는 리소스 접근 시. 등급/권한에 따라 접근 제한 구현에 사용.
• 404: 존재하지 않는 페이지나 리소스 요청 시 발생.

 

Flutter에서 401 에러 처리

401 에러가 발생하면 refresh 토큰이 있는지 확인하고, 있으면 access 토큰을 재발급받아 헤더를 갱신한 뒤 원래 요청을 재전송합니다.
refresh 토큰도 만료되면 로그아웃 처리합니다.

@override
void onError(DioException err, ErrorInterceptorHandler handler) async {
  final refreshToken = await storage.read(key: REFRESH_TOKEN_KEY);
  if (refreshToken == null) {
    return handler.reject(err);
  }
  final isStatus401 = err.response?.statusCode == 401;
  final isPathRefresh = err.requestOptions.path == '/refresh';
  if (isStatus401 && !isPathRefresh) {
    // 토큰 재발급 및 요청 재전송
  }
  return handler.reject(err);
}

• 401이면서 /refresh 요청이 아닐 때만 토큰 재발급을 시도해야 무한 루프를 방지할 수 있습니다.

 

Swift에서 401 에러 처리

401 에러이면서 /reissue 경로가 아닐 때만 토큰 재발급을 시도합니다.
새 토큰 발급 후 헤더에 적용, 원래 요청을 재실행합니다. 실패 시에는 에러 처리를 합니다.

if statusCode == 401 {
    if !requestPath.contains("/reissue") {
        // 토큰 재발급 및 요청 재실행
    }
}

• Flutter와 같은 원리로, 토큰 재발급 실패 시 적절한 에러 처리