415 Unsupported Media Type

사용법

415 Unsupported Media Type 오류 메시지를 받는 경우, 원인은 대개 서버가 Content-Type이나 Content-Encoding 헤더를 거부한 것입니다. 또는 서버가 메시지 본문을 더 들여다본 결과를 바탕으로 이 오류를 반환하기도 합니다.

후자의 경우, 서버는 콘텐츠를 파싱하거나 인식하는 데 실패했기 때문에 이 오류를 알립니다. 서버가 미디어 타입은 인식하지만 그 형식을 지원하지 않을 때 415 Unsupported Media Type이 가장 정확한 응답입니다. 콘텐츠에 구조적 오류가 있을 때는 400이나 422가 더 적절합니다.

이 오류는 406과 비슷하지만, 415 Unsupported Media Type은 Accept 헤더가 아니라 Content-Type 및 Content-Encoding 헤더에 기반한다는 점이 다릅니다.

SEO 영향

Google 같은 검색 엔진은 415 응답 상태를 가진 URL을 색인하지 않습니다. 이전에 색인된 URL은 검색 결과에서 제거됩니다.

예시

클라이언트는 평문 텍스트로 메시지를 보내려 하지만, 서버는 HTML 메시지만 받아들이므로 415 Unsupported Media Type을 보냅니다. 이후 클라이언트는 Content-Type 헤더만 바꾸고 원래 메시지는 그대로 둡니다. 서버는 본문이 유효한 HTML이 아님을 인식하고 요청을 두 번째로 거부합니다.

최초 요청

POST /blog/newmessage HTTP/1.1
Host: example.com
Content-Type: text/plain
Content-Length: 24

Good morning, Everybody!

Content-Type 헤더에 근거한 최초 응답

HTTP/1.1 415 Unsupported Media Type
Content-Type: text/html
Content-Length: 138

<html>
  <head>
    <title>Unsupported Format</title>
  </head>
  <body>
   <p>Please use HTML to post new messages.</p>
  </body>
</html>

검증을 우회하려 시도하는 후속 요청

POST /blog/newmessage HTTP/1.1
Host: example.com
Content-Type: text/html
Content-Length: 24

Good morning, Everybody!

메시지 본문 검사에 근거한 후속 응답

HTTP/1.1 415 Unsupported Media Type
Content-Type: text/html
Content-Length: 151

<html>
  <head>
    <title>Unsupported Format</title>
  </head>
  <body>
   <p>No HTML tags found. Use HTML to post messages.
   </p>
  </body>
</html>

해결 방법

Content-Type 헤더가 서버가 받아들이는 형식과 일치하는지 확인하세요. API 문서에는 대개 지원되는 미디어 타입이 나열되어 있습니다. 흔한 값으로는 application/json, application/xml, multipart/form-data, application/x-www-form-urlencoded가 있습니다.

본문 내용은 선언된 Content-Type과 일치해야 합니다. Content-Type: application/json으로 평문 텍스트를 보내면 서버가 본문을 JSON으로 파싱하려 하므로 실패합니다. 일부 서버는 charset 표기에 엄격합니다. charset=UTF-8 대신 charset=UTF8을 쓰면 특정 플랫폼에서 거부됩니다.

압축된 데이터를 보낼 때는 Content-Encoding 헤더를 확인하세요. 선언된 인코딩(예: gzip)과 본문의 실제 압축 형식이 어긋나면 415가 발생합니다.

파일 업로드의 경우 해당 파일 형식이 서버의 허용 목록에 있는지 확인하세요. 서버는 업로드를 JPEG, PNG, PDF 같은 특정 형식으로 제한하는 경우가 많습니다.

REST API 클라이언트에서 흔한 실수:

Postman이나 curl 같은 도구로 요청을 테스트하면 문제가 애플리케이션 코드에 있는지 요청 자체에 있는지 가려낼 수 있습니다. Postman은 본문 유형을 선택하면 Content-Type 헤더를 자동으로 설정합니다.

코드 참고

.NET

HttpStatusCode.UnsupportedMediaType

Rust

http::StatusCode::UNSUPPORTED_MEDIA_TYPE

Rails

:unsupported_media_type

http.StatusUnsupportedMediaType

Symfony

Response::HTTP_UNSUPPORTED_MEDIA_TYPE

Python3.5+

http.HTTPStatus.UNSUPPORTED_MEDIA_TYPE

Java

java.net.HttpURLConnection.HTTP_UNSUPPORTED_TYPE

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_UNSUPPORTED_MEDIA_TYPE

Angular

@angular/common/http/HttpStatusCode.UnsupportedMediaType