HTTP 415 Unsupported Media Type: 의미와 해결 방법

이 오류의 의미와 확인 방법

• API 클라이언트, 브라우저 폼, 업로드 도구, 모니터링 검사 또는 애플리케이션에서 415 Unsupported Media Type을 보고합니다.
• 다른 페이지와 경로는 계속 정상 작동하면서 특정 엔드포인트, HTTP 메서드 또는 요청 형식에만 응답이 영향을 줄 수 있습니다.
• 본문 형식, Content-Type, 콘텐츠 인코딩, 업로드 유형 또는 클라이언트 라이브러리를 변경한 후 요청이 실패할 수 있습니다.
• 응답 헤더에는 캐싱, 인증, 리디렉션 또는 rate limit 관련 정보와 함께 응답을 생성한 서버, 프록시 또는 CDN이 표시될 수 있습니다.
• HTTP 응답을 받았으므로 DNS 확인과 TLS 협상이 성공할 수 있지만, 이러한 검사는 요청 콘텐츠가 허용되었음을 의미하지 않습니다.

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

1. 지원되지 않는 요청 미디어 타입: 엔드포인트가 Content-Type에 전송된 값을 허용하지 않습니다. 예를 들어 JSON만 허용하는 경로에 form data를 전송하는 경우입니다.
2. 잘못되었거나 누락된 요청 헤더: 클라이언트가 Content-Type을 생략하거나 오타가 있는 값을 보내거나, 실제 형식과 다르게 본문을 표시합니다.
3. 지원되지 않는 콘텐츠 인코딩: 수신 구성 요소가 처리할 수 없는 압축 또는 전송 인코딩을 요청에서 사용합니다.
4. 잘못된 엔드포인트 또는 메서드: 다른 표현 형식, 업로드 형식 또는 HTTP 메서드를 요구하는 경로로 요청을 전송합니다.
5. 프록시, CDN, WAF 또는 웹 서버의 검증: 중간 계층이 애플리케이션에 도달하기 전에 요청을 거부하거나, 애플리케이션 문서에 명시된 요구 사항과 다른 규칙을 적용합니다.
6. 최근 애플리케이션 또는 설정 변경: 배포, 라우팅 변경, 파서 업데이트, 인증 통합 또는 프록시 규칙으로 인해 허용되는 요청 형식이 변경됩니다.

상태 코드만으로는 어느 구성 요소가 원인인지 알 수 없습니다. 인증, 권한, 제한 또는 업스트림 설정을 원인으로 판단하기 전에 요청 세부 정보와 해당 로그를 확인하세요.

해결 방법

방문자 및 비기술 사용자

1. 동일한 작업을 한 번만 다시 시도하세요. URL과 해당하는 경우 선택한 업로드 또는 폼 작업을 확인하세요. 동일한 요청을 반복해서 제출하지 마세요.
2. 일반적인 로그인 절차를 사용하세요. 엔드포인트에 계정이 필요한 경우 요청 헤더나 쿠키를 직접 변경하지 말고 사이트의 일반적인 인터페이스를 통해 로그인하세요.
3. 제출한 파일 또는 콘텐츠를 확인하세요. 업로드나 폼 제출 중 오류가 발생하면 사이트에서 요구하는 형식을 사용하고, 파일을 변환하지 않은 채 이름만 변경하지 마세요.
4. 사이트에서 지원하는 인터페이스를 사용해 보세요. API 도구, 브라우저 확장 프로그램 또는 사용자 지정 통합이 실패한다면 사이트의 일반 웹 폼이나 애플리케이션과 비교하세요.
5. 지속되면 사이트 소유자에게 문의하세요. 영향을 받은 URL 또는 기능, 대략적인 시간, HTTP 415 결과 및 실패한 작업을 포함하세요. 비밀번호, 쿠키, 인증 토큰 또는 비공개 파일 콘텐츠는 보내지 마세요.

개발자 및 API 클라이언트

1. 전체 요청 형태를 기록하세요. 메서드, URL 경로, 쿼리 매개변수, Content-Type, 콘텐츠 인코딩, 관련 Accept 값 및 본문에 대한 정제된 설명을 기록하세요. 불필요하게 비밀 정보나 개인정보를 로그에 남기지 마세요.
2. 요청을 엔드포인트 계약과 비교하세요. 해당 경로와 메서드가 전송하는 표현 형식을 허용하는지 확인하세요. 예를 들어 엔드포인트가 JSON, form-encoded data, multipart form data, XML 또는 특정 업로드 형식을 요구하는지 확인합니다.
3. 선언과 본문을 일치시키세요. form data를 JSON으로 표시하거나, 지원되는 해당 인코딩 없이 압축된 본문을 보내지 마세요. 클라이언트 라이브러리가 이 기능을 제공한다면 multipart boundary 생성은 라이브러리에 맡기세요.
4. 최소 재현을 사용하세요. 가능한 경우 선택적 필드와 관련 없는 미들웨어를 제거한 뒤, 지원되는 형식의 본문으로 동일한 요청을 반복하세요. 비교를 위해 원래 요청을 보존하세요.
5. 응답을 확인하세요. 상태, Content-Type, 캐싱 표시, 서버 또는 프록시 식별자, 리디렉션 및 오류 본문을 확인하세요. 게이트웨이가 생성한 응답은 애플리케이션 자체의 검증 결과를 반영하지 않을 수 있습니다.
6. 해당 계층의 로그를 확인하세요. 요청 타임스탬프, 경로 및 correlation 또는 request identifier를 애플리케이션, 웹 서버, reverse proxy, CDN 또는 WAF 로그와 대조하세요.
7. 가장 범위가 좁은 수정 사항을 적용하세요. 클라이언트 헤더, serializer, 업로드 형식, 경로 계약 또는 범위가 제한된 중간 계층 규칙을 수정하세요. 첫 대응으로 검증, 인증 또는 보안 필터링을 광범위하게 비활성화하지 마세요.
8. 다시 테스트하고 인접 동작을 확인하세요. 원래 요청을 반복한 다음, 지원되는 형식으로 동일한 엔드포인트를 테스트하고 관련 경로가 여전히 의도한 상태 코드를 반환하는지 확인하세요.

사이트 소유자 및 운영자

1. 동일한 클라이언트 유형과 요청 메서드로 실패를 재현하고, 정제된 헤더와 타이밍을 기록하세요.
2. 각 계층의 응답 헤더와 로그를 비교하여 415가 애플리케이션, 웹 서버, reverse proxy, CDN 또는 WAF 중 어디에서 생성되었는지 확인하세요.
3. 최근 배포와 라우팅, 요청 파싱, 업로드 처리, 프록시 전달, 콘텐츠 인코딩 및 보안 규칙 변경을 검토하세요.
4. 캐시 또는 중간 계층이 해당 요청에 부적절하게 저장된 응답을 제공하고 있지 않은지 확인하세요.
5. 특정 경로 또는 클라이언트 계약을 수정하고, 허용되는 형식을 문서화하며, 수정 사항을 확인할 수 있을 만큼 충분한 로그를 보관하세요.
6. 요청이 의도적으로 지원되지 않는 경우 엔드포인트 동작과 클라이언트용 문서에서 허용되는 형식을 명확히 안내해야 합니다.

예방 및 해결 확인 방법

• 중요한 각 엔드포인트에서 허용되는 HTTP 메서드, 미디어 타입, 인코딩 및 업로드 형식을 문서화하세요.
• 애플리케이션 또는 프록시를 변경한 후 대표적인 JSON, form, multipart 및 기타 지원 요청 형식에 대한 자동화 테스트를 실행하세요.
• 라우팅, 요청 파싱, 프록시, CDN 및 WAF 설정을 버전 관리하고 검토 가능한 변경 사항으로 관리하세요.
• 모든 4xx 응답을 하나의 범주로 취급하지 말고 경로와 메서드별로 상태 코드를 모니터링하세요.
• 관련 보존 기간 동안 correlation ID와 적절히 정제된 애플리케이션 및 중간 계층 로그를 사용할 수 있도록 유지하세요.
• 서버에서 허용하는 미디어 타입이 변경될 때 클라이언트 통합이 명확하게 실패하도록 하고, 문서화된 계약을 기준으로 테스트하세요.

자주 묻는 질문