405 에러? HttpRequestMethodNotSupportedException 원인과 1분 해결법 (당기시오 문을 미는 중!)

안녕하세요, 여러분의 든든한 IT 길잡이 데브프리입니다.

 

포스트맨(Postman)이나 프론트엔드에서 백엔드 서버로 정성스럽게 API 요청을 보냈는데, 데이터를 받아보기는커녕 아래와 같은 길고 무시무시한 에러 메시지와 함께 405 Method Not Allowed 상태 코드가 떨어질 때가 있습니다.

 

org.springframework.web.HttpRequestMethodNotSupportedException: Request method 'GET' not supported

(혹은 'POST' not supported)

"주소(URL)에 오타도 없고, 서버도 정상적으로 켜져 있는데 도대체 뭐가 문제라는 거지?"

 

초보 개발자들이 가장 많이 겪으면서도 은근히 원인을 찾지 못해 헤매는 이 에러! 오늘은 이 'HTTP 메서드 불일치 에러'의 원인을 아주 명쾌한 일상생활 비유로 알아보고, 단 1분 만에 허탈할 정도로 쉽게 해결하는 방법을 정리해 드리겠습니다.

1. 405 Method Not Allowed 에러, 도대체 넌 누구냐? (당기시오 문 비유)

에러 메시지를 천천히 읽어보면 정답이 숨어 있습니다. Request method 'GET' not supported라는 말은 "네가 지금 'GET' 방식으로 요청(Request)을 보냈는데, 우리 서버는 그 방식을 지원(Support)하지 않아!"라는 뜻입니다.

이 에러는 카페 문에 분명히 '당기시오'라고 적혀 있는데, 손님이 온 힘을 다해 문을 '밀고' 있어서 문이 열리지 않는 상황과 완벽하게 똑같습니다.

우리가 가게 문을 열 때 '밀기(Push)'와 '당기기(Pull)'라는 방식이 있듯, 웹 통신(HTTP)에도 데이터를 주고받는 방식인 메서드(GET, POST, PUT, DELETE 등)가 존재합니다.

 

스프링 부트 백엔드 개발자(가게 주인)는 회원가입 API를 만들면서 "여기는 데이터를 저장하는 곳이니까 무조건 POST 방식(당기기)으로만 들어와!"라고 문에 적어두었습니다(@PostMapping).

 

그런데 프론트엔드나 포스트맨(손님)이 문에 적힌 글씨를 무시하고 GET 방식(밀기)으로 문을 열려고 시도한 것입니다. 방식이 틀렸으니 스프링 부트는 가차 없이 "이 방식으로는 들어올 수 없어!"라며 405 에러를 뱉어냅니다.

 

2. 스프링 부트에서 이 에러가 발생하는 3가지 흔한 실수

가게 주인이 정해둔 규칙과 손님의 행동이 엇갈리는 가장 대표적인 3가지 상황과 해결책을 확인해 봅시다.

실수 ①: 포스트맨(Postman)에서 콤보박스 변경을 깜빡했을 때

가장 흔하게 발생하는 초보적인 실수입니다. 백엔드 컨트롤러에는 아래와 같이 @PostMapping으로 코드를 짜두었습니다.

Java

 

// 💡 POST 방식으로만 요청을 받겠다고 선언!
@PostMapping("/api/users")
public String createUser(@RequestBody UserDto userDto) {
    return "회원가입 성공";
}

하지만 포스트맨으로 테스트를 할 때, 주소창 옆의 HTTP 메서드 드롭다운을 POST로 바꾸지 않고 기본값인 GET 상태 그대로 Send 버튼을 눌러버린 경우입니다.

• 해결법: 포스트맨 주소창 좌측의 드롭다운을 GET에서 POST로 변경하고 다시 요청을 보내세요.

서버가 기대하는 연결 방식(메서드)과 클라이언트가 보내는 연결 방식이 톱니바퀴처럼 정확히 일치해야만 데이터가 무사히 통과할 수 있습니다.

실수 ②: HTML <form> 태그의 기본값이 GET인 것을 모를 때

프론트엔드(Thymeleaf, JSP 등)에서 폼 데이터를 전송할 때 발생합니다. HTML의 <form> 태그는 method 속성을 명시하지 않으면 무조건 GET 방식으로 데이터를 날려버립니다.

HTML

 

<!-- 🚨 에러 발생: method를 안 적으면 GET 방식으로 날아감 -->
<form action="/api/users">
    <input type="text" name="username">
    <button type="submit">가입하기</button>
</form>

<!-- ✅ 해결 방법: 명시적으로 method="post"를 적어주어야 함 -->
<form action="/api/users" method="post">
    <input type="text" name="username">
    <button type="submit">가입하기</button>
</form>

실수 ③: 브라우저 주소창에 직접 URL을 타이핑했을 때

백엔드 개발자가 API를 만들고 "잘 작동하나?" 궁금해서 크롬 브라우저 주소창에 http://localhost:8080/api/users를 직접 타이핑하고 엔터를 칠 때 발생합니다. 웹 브라우저의 주소창에 주소를 치고 엔터를 누르는 행위는 100% GET 방식입니다. POST나 PUT 방식의 API는 브라우저 주소창에서 엔터를 쳐서 테스트할 수 없으니, 반드시 포스트맨을 이용하셔야 합니다.

 

3. 요약: 트러블슈팅 체크리스트

HttpRequestMethodNotSupportedException (405 에러)가 떴다면 1분 만에 아래 2가지를 비교해 보세요.

1. 백엔드 코드 확인: 에러가 난 API 주소의 컨트롤러 위에 어떤 어노테이션이 붙어 있는지 확인합니다. (@GetMapping, @PostMapping, @PutMapping, @DeleteMapping 중 어느 것인가?)
2. 클라이언트 요청 확인: 포스트맨, Axios(React), HTML Form에서 보내는 방식이 1번에서 확인한 어노테이션과 정확히 똑같은 방식인지 확인합니다.

 

마무리

코드에 빨간 줄이 없는데 터지는 에러를 만나면 덜컥 겁부터 나기 마련입니다. 하지만 백엔드 서버 개발은 결국 '프론트엔드와 백엔드가 서로 약속한 규칙을 잘 지키고 있는지' 확인하는 과정의 연속입니다.

 

오늘 마주한 405 에러는 코드가 망가진 것이 아니라, 단순히 "밀어야 할 문을 당기고 있는 귀여운 실수"일 뿐입니다. 에러 메시지 안에 답이 있다는 사실을 기억하시고, 포스트맨의 메서드 박스를 다시 한번 꼼꼼히 확인해 보세요!

 

오늘 준비한 트러블슈팅 가이드가 여러분의 붉은 에러 창을 깨끗하게 지워주었기를 바랍니다. 오류를 고친 경험은 여러분의 가장 큰 자산이 됩니다. 막히는 에러가 있다면 언제든 댓글로 남겨주세요.

 

지금까지 데브프리였습니다. 감사합니다!