501 Not Implemented

사용법

501 Not Implemented 상태 코드는 서버 측의 기능 부족으로 서버가 요청을 수행할 수 없다는 뜻입니다. 이는 405 Method Not Allowed 상태 코드와 비슷하지만, 405는 요청된 메서드를 인식하지만 대상 리소스에는 허용하지 않는다는 뜻입니다.

405 Method Not Allowed 상태 코드는 서버가 그 메서드를 인식하지만 대상 리소스에 대해서는 허용하지 않는다는 뜻입니다. 501 Not Implemented 상태 코드는 서버가 그 메서드를 인식하지 못하거나 어떤 리소스에 대해서도 그 메서드를 지원할 능력이 없다는 뜻입니다. 이는 서버 수준의 영구적인 상태입니다.

이 상태는 서버가 요청 메서드를 인식하지 못해 어떤 리소스에 대해서도 그 요청을 지원할 수 없을 때 적절합니다.

SEO 영향

Google 같은 검색 엔진은 501 Not Implemented 상태를 반환하는 URL을 색인하지 않습니다. 이전에 색인되었다가 이 상태 코드를 반환하는 URL은 검색 결과에서 제거됩니다.

일부 API는 501의 의미를 메서드 미지원 너머로 확장합니다. Shopify API는 Shopify Plus 전용 기능처럼 요청한 엔드포인트가 해당 상점의 현재 요금제에서 사용 불가능할 때 501 Not Implemented를 반환합니다. 그 엔드포인트는 API 표면에는 존재하지만 구독 등급으로 막혀 있는 것입니다.

예시

클라이언트가 리소스를 요청하고, 요청 메서드는 인식되지만 아직 지원되지 않으므로 서버는 501 Not Implemented 상태 코드로 응답합니다.

요청

POST /requests?id=111&flag=start HTTP/1.1
Host: example.com

응답

HTTP/1.1 501 Not Implemented
Content-Type: text/html; charset=UTF-8
Content-Length: 148

<html>
  <head>
    <title>Function Not Implemented</title>
  </head>
  <body>
    <p>This functionality is under development.</p>
  </body>
</html>

해결 방법

요청의 HTTP 메서드가 올바른지 확인하세요. GET과 POST만 기대하는 서버에 PATCH를 보내면, 서버에 그 메서드에 대한 핸들러가 전혀 없는 경우 501이 발생합니다.

흔한 근본 원인과 해결책:

서버가 지원하지 않는 메서드. Apache에서는 Limit과 LimitExcept 지시문이 허용 메서드를 제어합니다. nginx에서는 location 블록에서 메서드 필터링이 이루어집니다. 클라이언트가 보내는 메서드가 설정에 의해 배제되지 않았는지 확인하세요.

서버 모듈 누락. Apache는 PROPFIND, MKCOL 같은 WebDAV 메서드에 mod_dav를 요구합니다. IIS는 WebDAV Publishing과 올바른 핸들러 매핑을 요구합니다. 해당 모듈을 활성화하고 서비스를 재시작하세요.

리버스 프록시가 메서드를 제거하거나 재작성. 일부 프록시는 비표준 메서드를 GET으로 변환합니다. nginx에서는 의도한 경우가 아니라면 proxy_method가 설정되어 있지 않은지 확인하세요. AWS ALB에서는 대상 그룹이 필요한 HTTP 메서드를 지원하는지 확인하세요.

오래된 서버 소프트웨어. 구버전 웹 서버 빌드는 출시 이후 표준화된 메서드를 지원하지 않습니다. Apache, nginx, IIS를 현재의 안정 버전으로 업데이트하세요.

방화벽이나 WAF의 차단. 웹 애플리케이션 방화벽과 보안 플러그인이 PUT, DELETE, OPTIONS 같은 메서드를 거부하기도 합니다. WAF 규칙을 검토하고 해당 엔드포인트에 필요한 메서드를 허용 목록에 넣으세요.

요금제 등급으로 제한된 API 기능. Shopify 같은 플랫폼은 엔드포인트가 존재하지만 해당 상점의 구독 수준에서는 사용할 수 없을 때 501을 반환합니다. API 문서에서 해당 기능의 요금제 요구 사항을 확인하고 필요하면 상향하세요.

클라이언트 측에서는 요청 URL이 올바른지 확인하세요. 오타로 트래픽이 잘못된 서버나 엔드포인트로 가면, 수신 서버에 그 메서드에 대한 구현이 없어 501이 반환됩니다.

코드 참고

.NET

HttpStatusCode.NotImplemented

Rust

http::StatusCode::NOT_IMPLEMENTED

Rails

:not_implemented

http.StatusNotImplemented

Symfony

Response::HTTP_NOT_IMPLEMENTED

Python3.5+

http.HTTPStatus.NOT_IMPLEMENTED

Java

java.net.HttpURLConnection.HTTP_NOT_IMPLEMENTED

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_NOT_IMPLEMENTED

Angular

@angular/common/http/HttpStatusCode.NotImplemented