HTTP 501 Not Implemented

HTTP 501의 의미

HTTP 501 Not Implemented는 요청을 처리하는 데 필요한 기능을 서버가 인식하지 못하거나 지원하지 않는다는 의미입니다. 스펙은 이를 주로 인식되지 않는 HTTP 메서드를 위해 예약해 두었습니다 — 서버는 어떤 리소스에 대해서도 해당 동사를 처리할 수 없으며, 이는 동사 자체는 알려져 있지만 해당 URL에서는 허용되지 않는 405와는 다릅니다.

실제로는 501이 프록시나 레거시 서버가 애초에 지원하도록 설계되지 않은 요청(WebDAV 동사, 오래된 스택에서의 PATCH 등)을 받았을 때, 또는 절반만 구성된 백엔드의 임시 응답으로 나타나기도 합니다.

501 오류의 일반적인 원인

• 서버가 전혀 구현하지 않은 HTTP 메서드입니다(예: 오래된 서버에서의 PATCH 또는 WebDAV 동사).
• 전달할 수 없는 요청 메서드를 받은 프록시나 게이트웨이입니다.
• 구현이 끝나기 전에 배포된 스텁 엔드포인트입니다.
• 버그가 있는 클라이언트로 인한 잘못된 형식의 메서드 이름입니다(GETT와 같은 오타).

개발자로서 해결하는 방법

• 전송되는 정확한 메서드를 확인하세요 — 오타나 대소문자가 잘못된 커스텀 동사는 의외로 흔합니다.
• 메서드가 정당한 경우(예: PATCH), 서버/프레임워크를 업그레이드하거나 이를 지원하도록 설정하거나, 스택이 허용하는 범위 내에서 오버라이드 헤더가 포함된 POST를 통해 우회하세요.
• 405와 구분하세요: 하나의 경로만 해당 동사를 거부한다면 그 경로를 수정하면 됩니다(405의 영역). 서버 전체가 그렇다면 플랫폼 자체의 기능 격차입니다.
• 프로덕션 API에서는 미완성 기능에 대해 501을 반환하지 마세요 — 501은 기본적으로 캐시가 가능하므로 404나 기능 플래그를 사용하는 것이 좋습니다.

응답 예시

HTTP/1.1 501 Not Implemented
Content-Type: application/json

{"error":"not_implemented","message":"PATCH is not supported by this server"}

자주 묻는 질문