501 Not Implemented: Method Unknown, Not Blocked

문제

501 Not Implemented를 받으면 자연스러운 해석 — “서버에서 뭔가 깨졌다” — 은 절반만 맞습니다. 501은 5xx 코드이니, 맞습니다, 서버가 실패를 인정하는 것입니다. 하지만 그건 아주 구체적인 인정이고, 그 구체성이 곧 해결책입니다. RFC 9110 §15.6.2는 501을 서버가 요청을 이행하는 데 필요한 기능을 지원하지 않을 때의 응답으로 정의하고 — 그 주된 경우를 짚습니다: 서버가 요청 메서드를 인식하지 못하며 어떤 리소스에 대해서도 지원할 수 없다. “안 한다”가 아니라 *“못 한다”*입니다. 당신이 보낸 메서드는 서버에 코드 경로가 없는 메서드입니다.

이 구분 하나가 사람들이 시간을 낭비하는 대부분을 걸러냅니다. 501은 크래시나 핸들러 버그, 잘못된 페이로드인 경우가 드뭅니다 — 그런 건 500을 줍니다. 501은 서버가 그 동사가 낯설다고 말하는 것입니다: 당신이 PATCH, PROPFIND, PURGE, 또는 더 이색적인 무언가를 보냈고, 서버 또는 당신과 서버 사이의 무언가가 그 메서드를 배운 적이 없는 것입니다. 그러니 질문은 결코 “내 코드가 왜 실패했지?”가 아닙니다. “이 요청 경로에서 누가 이 메서드를 구현하지 않는가?”입니다.

증상

• 응답 상태줄이 501 Not Implemented로 뜨고, 본문은 흔히 애플리케이션의 오류 형식이 아니라 일반 서버·프록시 오류 페이지입니다.
• 비표준이거나 덜 흔한 메서드 — PATCH, PUT, DELETE, WebDAV 동사, CDN PURGE — 에서 나타나고, 같은 호스트에 대한 평범한 GET/POST는 잘 됩니다.
• Postman이나 curl 같은 도구로는 즉시 재현되지만, 브라우저로는 드뭅니다 — 브라우저는 대부분 GET과 POST를 보내니까요.
• 배포를 해도 오류가 살아남을 수 있습니다. 캐시가 501을 저장할 수 있기 때문입니다.

주요 원인 3가지

1. 서버가 정말로 그 메서드를 구현하지 않음 - 정직한 경우입니다. GET/POST만 연결한 스택에 PATCH를 호출했거나, WebDAV 없는 서버에 WebDAV 메서드(PROPFIND, MKCOL)를 쳤거나, 오타 났거나 커스텀인 동사를 보낸 것입니다. IIS는 이에 대해 명시적입니다 — 인식 못 하는 메서드에 501을 반환하고, 대부분의 서버가 이를 따릅니다. 해결은 메서드를 켜거나 구현하는 것, 아니면 그걸 보내지 않는 것입니다.
2. 경로의 프록시·로드밸런서·CDN이 메서드를 떨어뜨림 - 교활한 경우입니다. 당신 오리진은 멀쩡하거든요. 메서드를 이해 못 하는 중간 노드가 오리진을 대신해 501로 답할 수 있어, 요청이 도착조차 못 합니다. 캐시 제어 동사(PURGE, BAN)와 오래되거나 최소 설정된 게이트웨이에서 흔합니다. 단서: 오리진을 직접 치면 되고 공개 호스트명으로는 실패한다는 것.
3. 게이트웨이가 업스트림 핸들러를 잃었거나 라우팅 오류 - 특정 메서드를 죽었거나 매핑 안 됐거나 재설정된 앱 서버로 넘기도록 설정된 리버스 프록시가, 특히 라우팅 키가 메서드 자체일 때, 502가 아니라 501을 드러낼 수 있습니다. 여기선 메서드가 어딘가에는 구현돼 있지만, 그 어딘가로 가는 경로가 끊긴 것입니다.

DechoNet으로 진단

• HTTP 점검은 URL에 대한 원시 상태와 응답 헤더를 보여줍니다. 평범한 요청은 200인데 특정 메서드가 501이면, 사이트는 살아 있고 문제가 메서드 범위임을 확인한 것입니다 — 이제 어느 홉이 동사를 거부하는지 찾으세요.
• DNS 점검은 호스트명이 프록시/CDN을 가리키는지 오리진을 곧장 가리키는지 드러냅니다. CDN 대역으로 해석되면, 그 메서드를 구현해야 하는 중간 노드가 있는 것이고 — 오리진 단독으로는 될 때의 첫 번째 용의자입니다.

해결 체크리스트

• 정확한 메서드로 재현하세요: curl -X PATCH -i https://yourdomain.com/path. 같은 URL을 GET으로 재시도해, 경로나 본문이 아니라 동사가 문제임을 확인합니다.
• 프록시·CDN을 우회해 오리진을 직접 테스트하세요(올바른 Host 헤더로 오리진 IP 사용, 또는 스테이징 URL). 오리진은 되고 공개 URL은 실패 → 중간 노드가 범인입니다.
• 서버가 그 메서드를 지원해야 한다면 켜세요: WebDAV 모듈 활성화, 라우트/핸들러 추가, 또는 프레임워크에서 메서드 허용. 정당하게 지원하지 말아야 한다면, 호출자가 그걸 그만 보내야 하거나 — 클라이언트가 무엇이 지원되는지 배우도록 Allow 헤더를 실은 405를 반환해야 합니다.
• 프록시/CDN이 메서드를 떨어뜨리면, 그 동사를 업스트림으로 전달하도록 설정하세요(많은 게이트웨이가 메서드를 명시적으로 화이트리스트합니다). 이제 요청이 오리진 로그에 닿는지 확인합니다.
• 수정 후 그 경로를 캐시에서 퍼지하세요. 501은 기본 캐시 가능이라, 이미 정상인 서버 위로 오래된 사본이 오류를 계속 낼 수 있습니다.

에스컬레이션 시점

• 오리진이 메서드를 구현하고, 앞에 프록시도 없는데 여전히 501이면, 전체 요청·응답 헤더를 캡처하세요. 동사를 명백히 지원하는 소프트웨어에서 나온 501은 요청을 재작성하는 특정 미들박스나 WAF 규칙을 가리킵니다 — 버그가 아니라 그 박스를 찾으세요.
• 매니지드 플랫폼이나 CDN이 당신에게 필요한 메서드(PURGE, PATCH)에 501을 반환하면, 그건 그들의 메서드 허용목록이고, 해결은 오리진에서 패치할 수 있는 게 아니라 그쪽의 설정이나 지원 요청입니다.
• 메서드를 의도적으로 거부하려던 거라면, 501로 두지 마세요. 501은 “우리가 못 한다”고 말해 클라이언트의 재시도와 캐시의 저장을 부릅니다. 대신 올바른 Allow 헤더를 실은 405를 반환하세요 — “우리는 할 수 있다, 다만 이 방식은 아니다”라고 말하며 클라이언트에게 다음에 뭘 할지 정확히 알려줍니다.