HTTP 415 Unsupported Media Type — 미디어 타입 미지원 원인·해결

HTTP 415 Unsupported Media Type — 미디어 타입 미지원 원인·해결

API에 데이터를 보냈더니 415 Unsupported Media Type이 돌아온다. 데이터 내용은 멀쩡한데 거절당했다. 415는 "요청 본문의 형식(미디어 타입)을 이 자원이 지원하지 않는다"는 뜻이다. 가장 흔한 경우가 서버는 JSON만 받는데 다른 형식을 보냈거나, Content-Type 헤더를 빠뜨렸거나 잘못 지정한 것이다. 형식이 깨진 400과도, 응답 협상이 실패한 406과도 다르다. 415는 "보낸 형식 자체를 못 받는다"는 신호다. 이 글은 415가 정확히 무엇인지, 왜 나는지, Content-Type을 어떻게 맞추는지를 정리한다.

HTTP 415 Unsupported Media Type

이 글의 구성

 

🔎415 Unsupported Media Type의 의미

🧩자주 나오는 발생 원인 4가지

💻재현과 Content-Type 확인

⚖️400·406과의 차이

🛠해결 방법과 설계 원칙

💬자주 묻는 질문 5가지

---

🔎 415 Unsupported Media Type의 의미

415는 4xx, 클라이언트 요청에 문제가 있다는 묶음이다. 정확히는 "요청 본문의 미디어 타입(또는 인코딩)을 대상 자원이 그 메서드로는 지원하지 않는다"는 뜻이다. 서버가 본문을 받긴 했지만, 그 형식을 처리할 방법이 없어 거절한 것이다.

여기서 핵심은 Content-Type 헤더다. 요청 본문이 어떤 형식인지(JSON·XML·폼·이미지 등)를 알려주는 게 Content-Type인데, 서버가 그 형식을 받도록 만들어지지 않았으면 415가 난다. 예를 들어 JSON API에 application/xml로 보내거나, Content-Type을 아예 안 붙이거나, text/plain으로 잘못 붙이면 서버는 "이 형식은 못 받는다"고 답한다.

핵심 — 내용이 아니라 "형식 종류"의 문제

415는 데이터 값이 틀린 게 아니라, 데이터의 형식 종류 자체를 서버가 안 받는다는 뜻이다. 같은 내용이라도 Content-Type을 서버가 지원하는 형식으로 바꿔 보내면 통과한다. 그래서 415 디버깅의 첫걸음은 "내가 보낸 Content-Type"과 "서버가 받는 Content-Type"을 맞춰 보는 것이다.

---

🧩 자주 나오는 발생 원인 4가지

원인 1 — Content-Type 헤더 누락·오타

가장 흔하다. JSON을 보내면서 Content-Type을 안 붙이거나, application/json을 application/josn처럼 잘못 적은 경우다. 미디어 타입을 검증하는 서버는 형식을 못 알아봐 415로 거절할 수 있다.

원인 2 — 서버가 받는 형식과 불일치

서버는 application/json만 받는데 application/xml이나 form 형식으로 보낸 경우다. 자원이 그 미디어 타입을 처리하도록 설계되지 않아 415가 난다. API 문서가 정한 형식과 어긋난 것이다.

원인 3 — 서버가 미디어 타입을 명시적으로 제한

Spring의 consumes, ASP.NET Core의 [Consumes]처럼 엔드포인트가 받을 미디어 타입을 못 박아 두면, 그 밖의 Content-Type은 415로 거절된다. 참고로 순수 Express의 express.json()은 매칭 안 되는 타입을 조용히 건너뛰어, 415가 아니라 req.body가 비어 생기는 후속 에러로 이어진다.

원인 4 — 파일 업로드 형식·인코딩 미지원

허용하지 않는 파일 형식을 올리거나, 서버가 지원하지 않는 Content-Encoding(압축 방식)으로 보낸 경우다. 415는 본문 형식뿐 아니라 인코딩이 안 맞을 때도 난다.

---

💻 재현과 Content-Type 확인

415는 미디어 타입을 검증하는 서버에 안 받는 Content-Type으로 보내면 재현된다. 형식을 못 박아 둔 JSON API에 일부러 다른 형식을 지정해 본다.

# JSON 서버에 text/plain 으로 보냄 → 415
curl -i -X POST https://example.com/api/users \
  -H 'Content-Type: text/plain' \
  -d '{"name": "kim"}'

# 응답 — 이 형식은 못 받는다
HTTP/1.1 415 Unsupported Media Type

해결은 서버가 받는 형식으로 Content-Type을 바꾸는 것이다. JSON이면 application/json을 정확히 지정한다.

# ✓ 올바른 Content-Type 지정 → 정상
curl -i -X POST https://example.com/api/users \
  -H 'Content-Type: application/json' \
  -d '{"name": "kim"}'

# 파일 업로드는 multipart/form-data 사용
curl -i -X POST https://example.com/upload \
  -F 'file=@photo.jpg'

개발자도구 네트워크 탭에서 실패한 요청의 요청 헤더(Request Headers)에 Content-Type이 무엇으로 갔는지 확인하고, API 문서가 요구하는 형식과 비교하면 원인이 거의 드러난다.

---

⚖️ 400·406과의 차이

415는 비슷한 4xx 코드와 헷갈리기 쉽다. 무엇이 안 맞는지에 따라 코드가 갈린다.

코드	무엇의 문제	방향
415	요청 본문의 형식(Content-Type)을 지원 안 함	요청 본문
400	요청 구문·형식 자체가 깨짐	요청 전반
406	Accept에 맞는 응답을 만들 수 없음	응답 협상

세 코드의 갈림길은 "어디의 형식이 문제인가"다. 415는 내가 보낸 요청 본문의 형식을 서버가 못 받는 것이고, 406 Not Acceptable은 반대로 내가 Accept 헤더로 요구한 응답 형식을 서버가 만들지 못하는 것이다. 즉 415는 요청 방향, 406은 응답 방향이다. 400은 형식 종류가 아니라 요청 구문 자체가 깨진 경우다. Content-Type을 안 받아 막혔다면 거의 415다.

---

🛠 해결 방법과 설계 원칙

415는 거의 항상 "Content-Type을 서버가 받는 형식으로 맞추면" 풀린다. 호출하는 쪽과 만드는 쪽의 할 일이 다르다.

입장	할 일
호출하는 쪽	API 문서가 요구하는 Content-Type을 정확히 지정
파일 업로드	multipart/form-data 사용, 허용 형식·확장자 확인
백엔드	필요한 형식의 파서·미들웨어 등록, 지원 타입 명시
에러 설계	415 응답에 지원하는 미디어 타입을 안내

단계별 진단 절차

01내가 보낸 Content-Type을 확인한다(개발자도구 요청 헤더).

02API 문서가 요구하는 형식과 비교한다(JSON·폼·멀티파트 등).

03올바른 Content-Type으로 바꿔 다시 보낸다(오타·charset 포함).

04서버라면 받을 형식의 파서·미들웨어가 등록됐는지 확인한다.

05파일 업로드면 허용 형식·인코딩과 multipart 사용 여부를 점검한다.

설계 관점에서 한 가지 더. 415 응답에 "지원하는 미디어 타입"을 안내해 주면 호출하는 쪽이 헤매지 않는다. 그냥 415만 던지지 말고, 본문이나 문서에 "이 엔드포인트는 application/json만 받는다" 같은 정보를 명확히 남기는 게 좋은 설계다.

“

415는 내용이 아니라 형식 종류의 문제다. 내가 보낸 Content-Type과 서버가 받는 형식을 맞추면 대개 풀린다.

 

— 보낸 형식과 받는 형식을 맞춰라

---

💬 자주 묻는 질문 5가지

Q1데이터는 맞는데 왜 415가 나죠?

데이터 값이 아니라 형식 종류가 문제이기 때문입니다. Content-Type 헤더로 알린 형식을 서버가 안 받는 것이죠. JSON API에 다른 형식을 보냈거나 Content-Type을 빠뜨린 경우가 흔합니다. 서버가 받는 형식으로 Content-Type을 맞추면 풀립니다.

Q2415랑 400은 뭐가 다른가요?

400은 요청 구문·형식 자체가 깨진 것이고, 415는 형식은 멀쩡하지만 그 미디어 타입을 서버가 지원하지 않는 것입니다. JSON 문법은 맞는데 Content-Type이 안 맞아 막혔다면 415, JSON 자체가 깨졌으면 400입니다.

Q3415랑 406은요?

방향이 반대입니다. 415는 내가 보낸 요청 본문의 형식(Content-Type)을 서버가 못 받는 것이고, 406 Not Acceptable은 내가 Accept 헤더로 요구한 응답 형식을 서버가 만들지 못하는 것입니다. 415는 요청 방향, 406은 응답 방향이라고 기억하면 됩니다.

Q4Content-Type을 붙였는데도 415예요.

오타이거나(application/josn 등), 서버가 그 형식을 처리하는 파서·미들웨어를 등록하지 않았을 수 있습니다. 또 charset이나 정확한 타입 표기가 어긋난 경우도 있죠. 서버 쪽에서 해당 형식 파서가 켜져 있는지, 문서가 요구하는 정확한 타입 문자열인지 확인하세요.

Q5파일 업로드에서 415가 나요.

서버가 허용하지 않는 파일 형식을 올렸거나, 잘못된 Content-Type·인코딩으로 보낸 경우입니다. 파일 업로드는 보통 multipart/form-data로 보내야 하고, 서버가 허용하는 확장자·MIME 타입 안에서 올려야 합니다. 허용 형식 목록을 문서에서 확인하세요.

---

📌 결론

415 Unsupported Media Type은 "요청 본문의 형식을 이 자원이 지원하지 않는다"는 신호다. 데이터 값이 틀린 게 아니라, Content-Type으로 알린 형식 종류를 서버가 못 받는 것이다. 그래서 해결은 "보낸 형식과 받는 형식을 맞추는" 데서 시작한다.

실무 원칙은 다음과 같다.

📦 Content-Type을 맞춘다. 415의 거의 모든 원인은 요청 본문 형식과 서버 지원 형식의 불일치다. 내가 보낸 Content-Type부터 확인한다.

🔌 서버 파서를 점검한다. 받을 형식의 파서·미들웨어가 등록됐는지, 정확한 타입 문자열·charset인지 본다.

🧭 400·406과 구분한다. 형식 종류 미지원은 415, 구문 깨짐은 400, 응답 협상 실패는 406이다. 방향을 헷갈리지 않는다.

415 트러블슈팅 체크리스트

01요청 헤더의 Content-Type 값 확인.

02API 문서가 요구하는 형식과 대조(JSON·폼·멀티파트).

03오타·charset 점검 후 올바른 Content-Type으로 재요청.

04서버에 해당 형식 파서·미들웨어 등록 여부 확인.

05파일 업로드는 multipart·허용 형식·인코딩 점검.

06415·406 방향 구분 — 요청 형식 vs 응답 협상.

---

본 글은 HTTP 415 응답의 일반적 원인과 해결 방법을 정리한 자료다. 서버·파서 설정 변경은 영향 범위를 확인한 뒤 신중히 적용한다.

 

#HTTP415 #UnsupportedMediaType #415에러 #ContentType #미디어타입 #JSON #multipart #406과차이 #400과차이 #RESTAPI #Express #파일업로드 #API에러 #웹개발 #백엔드