HTTP 501 Not Implemented: 의미와 해결 방법

이 오류의 의미와 확인 방법

• 브라우저, API 클라이언트, 모니터링 서비스 또는 HTTP 검사기가 501 Not Implemented를 수신합니다.
• 응답이 특정 URL, HTTP 메서드, 프로토콜 기능 또는 요청 형식에서만 발생할 수 있습니다.
• 다른 페이지나 API 엔드포인트는 정상적으로 계속 작동할 수 있습니다.
• 응답 헤더에 서버 또는 중간 구성 요소가 표시될 수 있으며, 캐싱, 인증, 리디렉션 또는 프록시 관련 정보가 포함될 수 있습니다.
• HTTPS 요청에서 HTTP 501을 받았다는 것은 해당 요청에 필요한 연결 계층이 완료된 후 요청이 HTTP를 처리하는 엔드포인트에 도달했다는 의미입니다. 모든 DNS, TLS 또는 네트워크 경로가 정상이라는 뜻은 아닙니다.

가능성이 높은 순서의 주요 원인

가장 구체적인 원인부터 일반적이지 않은 원인까지

1. 요청된 HTTP 기능이 지원되지 않습니다. 서버 또는 애플리케이션이 요청된 메서드, 프로토콜 동작, 요청 기능 또는 경로 기능을 구현하지 않았을 수 있습니다.
2. 경로 또는 메서드가 지원되지 않는 핸들러에 매핑되어 있습니다. 예를 들어 배포된 시스템에 경로는 노출되어 있지만, 해당 요청을 처리하도록 설계된 애플리케이션 로직에 연결되지 않았을 수 있습니다.
3. reverse proxy, CDN, WAF 또는 gateway가 응답을 생성했습니다. 중간 구성 요소가 요청이 애플리케이션에 도달하기 전에 요청을 거부하거나 처리를 수행하지 않을 수 있습니다.
4. 설정 또는 배포 변경으로 요청 처리가 달라졌습니다. 라우팅, 프록시, 서버 또는 애플리케이션 변경으로 이전에 지원되던 요청을 더 이상 처리하지 못할 수 있습니다.
5. 요청이 엔드포인트에서 지원하는 계약과 일치하지 않습니다. 특이한 메서드, 프로토콜 세부 사항, 콘텐츠 유형 또는 요청 형식으로 인해 지원되지 않는 코드 경로가 실행될 수 있습니다. 모든 요청 불일치를 501로 간주하지 말고, 문서화된 엔드포인트 동작을 확인하세요.

인증 실패, 권한 부여 실패, rate limit 및 잘못된 요청에는 일반적으로 다른 상태 코드가 사용됩니다. 501의 원인으로 판단하기 전에 전체 응답과 로그를 확인하세요.

해결 방법

방문자 또는 API 소비자인 경우

1. 정확한 URL을 한 번 다시 요청하고 주소, 경로, 쿼리 매개변수 및 요청 메서드가 올바른지 확인하세요.
2. 엔드포인트에 일반적으로 계정이 필요한 경우 사이트의 정상적인 절차를 통해 로그인한 후 다시 시도하세요. 신뢰할 수 없는 엔드포인트로 자격 증명을 전송하지 마세요.
3. API 클라이언트를 사용하는 경우 메서드와 요청 형식을 엔드포인트 문서와 비교하세요. 브라우저 방문에는 GET이 사용될 수 있지만, API 작업에는 다른 메서드가 필요할 수 있습니다.
4. 응답 헤더와 본문에서 서버, 프록시, 인증, 리디렉션 또는 캐싱 관련 단서를 확인하세요. 진단 정보를 공유할 때 쿠키, authorization 헤더, API 키 또는 기타 비밀 정보를 노출하지 마세요.
5. 서비스가 실패 중이거나 제한을 표시하는 경우 반복적으로 요청하지 마세요. URL, 메서드, 대략적인 시간, 응답 상태 및 관련 헤더의 비식별화된 사본을 기록하세요.
6. 오류가 계속되면 해당 정보를 사이트 또는 API 소유자에게 보내세요. 지원되지 않는 서버 측 기능은 응답한 서비스를 운영하는 주체만 수정할 수 있습니다.

웹사이트 또는 API를 운영하는 경우

1. 실패한 요청을 정확히 수집하세요. HTTP 메서드, URL, 쿼리 매개변수, 라우팅과 관련된 요청 헤더, 상태 코드, 응답 헤더 및 비식별화된 응답 본문을 기록하세요. 성공하는 요청과 비교하세요.
2. 이 동작이 의도된 것인지 확인하세요. 해당 경로와 메서드가 지원되어야 하는지 확인하세요. 메서드가 구현되지 않은 것이 아니라 허용되지 않은 경우 의도된 응답은 405와 같은 다른 상태 코드일 수 있습니다. 서비스의 실제 계약과 구현을 기준으로 판단하세요.
3. 응답을 생성한 계층을 확인하세요. 501이 애플리케이션, 웹 서버, reverse proxy, CDN, WAF, API gateway 또는 다른 중간 구성 요소에서 발생했는지 확인하세요. 헤더만으로는 추정에 그칠 수 있으므로 타임스탬프가 포함된 로그로 검증하세요.
4. 일치하는 로그를 확인하세요. 관련된 각 계층에서 동일한 요청 시간, 경로, 메서드, 요청 식별자 및 upstream 결과를 검색하세요. 가장 외부에 있는 구성 요소에서 시작해 애플리케이션 방향으로 요청을 추적하세요.
5. 최근 변경 사항을 검토하세요. 배포 내역과 라우팅, 서버 모듈, 프록시 규칙, API 핸들러, CDN 동작, WAF 정책 및 프로토콜 설정 변경 사항을 비교하세요. 문제가 발생한 경로 또는 메서드에 영향을 준 변경 사항에 집중하세요.
6. 가장 작은 안전한 요청으로 재현하세요. 문제를 재현하는 데 필요한 메서드와 경로는 유지하면서 불필요한 헤더와 페이로드 필드를 제거하세요. 가능하면 먼저 승인된 non-production 환경에서 테스트하세요.
7. 가장 좁은 범위의 수정 방법을 적용하세요. 의도한 핸들러를 복원하거나 특정 경로 또는 중간 구성 요소 규칙을 조정하세요. 로그에서 직접적인 원인임을 보여 주고 변경이 승인된 경우가 아니라면 광범위한 보안, 인증, 권한 또는 프록시 변경을 피하세요.
8. 원래 요청과 관련 동작을 다시 테스트하세요. 실패한 요청에서 예상되는 상태, 응답 본문 및 헤더가 반환되는지 확인한 다음 관련 경로와 메서드를 테스트해 수정으로 인해 더 넓은 문제가 발생하지 않았는지 확인하세요.
9. 의도된 동작을 문서화하세요. 지원되지 않는 기능에 대해 501이 예상되는 경우 지원되는 메서드와 클라이언트에 표시되는 동작을 기록하여 모니터링 시스템과 사용자가 응답을 원인 불명의 장애로 오인하지 않도록 하세요.

예방 및 해결 확인 방법

• 전체 가용성만 추적하지 말고 경로, 메서드 및 배포별 HTTP 상태 코드 비율을 모니터링하세요.
• 애플리케이션 라우팅, 웹 서버, 프록시, CDN, WAF 및 gateway 설정을 버전 관리하세요.
• 릴리스 및 중간 구성 요소 설정 변경 후 지원되는 HTTP 메서드와 주요 API 경로를 테스트하세요.
• 의도적으로 지원하지 않는 경로와 메서드 및 클라이언트에 표시할 예상 응답을 문서화하세요.
• 응답과 응답을 생성한 계층을 연결할 수 있도록 상관관계가 있는 로그와 요청 식별자를 충분히 오래 보관하세요.
• 일반적인 홈페이지 요청만 사용하지 말고 주요 클라이언트에 필요한 실제 경로와 메서드를 실행하는 상태 확인을 사용하세요.

자주 묻는 질문