HTTP 415 Unsupported Media Type Hatası Nasıl Çözülür?

HTTP 415 hatası, sunucunun isteğin gövdesinde gönderilen medya türünü anlayamadığını veya bu medya türünü ilgili endpoint için işleyemediğini gösterir. Çözüm için öncelikle Content-Type başlığını istek gövdesiyle eşleştir; ardından endpoint’in beklediği veri biçimini, Accept başlığını ve sunucunun gövdeyi ayrıştırma davranışını kontrol et.

Bu hata tek bir nedene indirgenemez. URL, HTTP metodu, başlıklar, istek gövdesi ve sunucu tarafındaki parser birlikte değerlendirilmelidir. Bir API’nin 415 yanıt koşulları ve hata gövdesinde kullandığı alan adları için ilgili endpoint dokümantasyonu belirleyicidir.

HTTP 415 Unsupported Media Type Hatası Ne Anlama Gelir?

HTTP 415, istemcinin gönderdiği veri formatının sunucu tarafından desteklenmediği ya da beklenen formatta tanınmadığı durumlarda görülebilir. Örneğin JSON gönderen bir istekte Content-Type: application/json başlığı bulunmuyorsa sunucu, gövdeyi JSON olarak ayrıştıramayabilir. Tersine, form verisi bekleyen bir endpoint’e JSON gönderilmesi de aynı türden bir uyumsuzluk oluşturabilir.

Burada önemli ayrım şudur: Content-Type, istemcinin gönderdiği gövdenin formatını belirtir. Accept ise istemcinin sunucudan almak istediği yanıt formatını ifade eder. Bu nedenle yalnızca Accept: application/json eklemek, JSON olarak gönderilmemiş bir istek gövdesini düzeltmez.

Bir isteğin doğru formatta olması da tek başına yeterli değildir. İsteği doğru endpoint’e ve doğru HTTP metoduyla gönderdiğinden emin olmalısın. Yanlış endpoint’e doğru biçimde gönderilen bir gövde, beklenmeyen bir parser veya farklı medya türü kuralıyla karşılaşabilir. Ayrıca sunucu tarafında gövdeyi ayrıştıran katman, belirli medya türlerini kabul edecek şekilde yapılandırılmış olabilir.

HTTP 415 Teşhisinde Kontrol Edilecek Altı Alan

Aşağıdaki sıra, hatayı rastgele başlık değiştirerek değil, neden-sonuç ilişkisiyle incelemeni sağlar:

1. URL ve endpoint: İsteğin gerçekten hedeflediğin kaynağa gittiğini kontrol et. Önce endpoint dokümantasyonundaki yolu doğrula. Yanlış endpoint’e doğru formatta istek gönderiyor olabilirsin. URL doğruysa sonraki adıma geç.
2. HTTP metodu: POST, PUT veya PATCH gibi gövde taşıyan metodun dokümantasyonda beklenen metot olduğundan emin ol. Metot doğru değilse gövde ve medya türü kuralları farklı olabilir.
3. Content-Type: Gövde JSON ise genellikle application/json, URL-encoded form ise application/x-www-form-urlencoded kullanılır. Başlık ile gerçek gövde aynı formatı göstermiyorsa 415 oluşabilir.
4. Accept: Sunucudan beklediğin yanıt türünü belirtir. Bu başlığı, istek gövdesinin formatını belirleyen Content-Type ile karıştırma.
5. İstek gövdesi: JSON gövdesinin geçerli JSON olup olmadığını, alan adlarının ve veri türlerinin endpoint sözleşmesine uyduğunu kontrol et. Geçerli görünen bir gövde, endpoint’in beklediği medya türüyle yine de eşleşmeyebilir.
6. Sunucu parser’ı: Gövdeyi ayrıştıran katmanın ilgili medya türünü okuyup okuyamadığını incele. Bu davranış framework adına göre varsayılmamalı; kullanılan API’nin birincil endpoint dokümantasyonu ve sunucu yapılandırması kontrol edilmelidir.

Content-Type, Accept ve İstek Gövdesi Nasıl Eşleştirilir?

HTTP 415 hatasını çözmenin temel kuralı şudur: İstek gövdesinin biçimi, Content-Type başlığıyla aynı olmalıdır. Sunucu, başlıktaki medya türüne göre gövdeyi hangi parser ile okuyacağını belirler. Endpoint dokümantasyonunda kabul edilen medya türlerini, charset kullanımını ve yanıt içerik anlaşmasını ayrıca kontrol etmelisin; her API aynı türleri kabul etmeyebilir.

JSON kullanırken nesne süslü parantezle başlar ve biter. Alan adları ile string değerler çift tırnak içinde yazılır; virgül ise alanları ayırır. Sayısal değerler tırnaksız yazılır: "age":20 bir sayıdır, "age":"20" ise metindir. Bu fark, medya türü doğru olsa bile sunucu tarafındaki doğrulamada sorun oluşturabilir.

Content-Type eksikse sunucu gövdeyi hangi biçimde okuyacağını anlayamayabilir. Başlık gövdeyle uyumsuzsa örneğin JSON metni form verisi gibi yorumlanmaya çalışılır ve 415 dönebilir. Desteklenmeyen bir medya türü belirtmek de aynı sonuca yol açabilir.

Accept başlığı farklı bir göreve sahiptir: Sunucuya, yanıtı hangi formatta almak istediğini bildirir. Örneğin Accept: application/json, yanıtın JSON olmasını beklediğini ifade eder. Bu nedenle 415 hatasının doğrudan nedeni çoğunlukla Content-Type ile istek gövdesi arasındaki uyumsuzluktur; ancak sunucunun yanıt içerik anlaşması kuralları endpoint’e göre değişebilir. Gönderdiğin başlıkları ve kabul edilen medya türlerini dokümantasyonla karşılaştır.

Postman, Python ve Java’da Doğru İstek Nasıl Kurulur?

Postman ile JSON isteği gönderme

1. İstek yöntemini ve endpoint adresini seç.
2. Body sekmesine geçerek raw seçeneğini işaretle.
3. Raw alanının biçim menüsünden JSON seç.
4. Gövdeye geçerli bir JSON nesnesi yaz.
5. Headers sekmesinde gönderilen Content-Type değerinin application/json olduğunu kontrol et.

Postman, raw gövde için seçtiğin biçime göre başlık oluşturabilir; ancak elle eklenen bir Content-Type değeri otomatik değerin önüne geçebilir. Bu yüzden isteği göndermeden önce gerçekten iletilen başlığı kontrol et.

Python örneği

import requests

url = "https://api.example.com/users"
payload = {
    "name": "Ada",
    "age": 20
}

response = requests.post(
    url,
    json=payload,
    headers={
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
)

print(response.status_code)
print(response.text)

Bu örnekte sunucuya JSON gövdesiyle birlikte Content-Type: application/json gönderilmesi beklenir. Accept ise mümkünse JSON yanıt istediğini belirtir. Endpoint farklı bir medya türü bekliyorsa dokümantasyondaki değer kullanılmalıdır.

Java örneği

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ApiClient {
    public static void main(String[] args) throws Exception {
        String json = "{"name":"Ada","age":20}";

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.example.com/users"))
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();

        HttpResponse<String> response =
                HttpClient.newHttpClient().send(
                        request,
                        HttpResponse.BodyHandlers.ofString()
                );

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Java örneğinde beklenen eşleşme, JSON metni ile application/json başlığının birlikte gönderilmesidir. Kullanılan HTTP istemci kütüphanesinin varsayılan başlık ve karakter kodlaması davranışını ayrıca kontrol etmelisin; bu örnek, tüm framework’lerin otomatik olarak aynı şekilde davrandığı anlamına gelmez.

Python veya Java ile istemci geliştirme pratiğini düzenli bir öğrenme planıyla ilerletmek istersen birebir online yazılım eğitimi seçeneklerini inceleyebilirsin.

Hatalı İstekten Doğru İsteğe Tek Değişiklikle İlerleme

HTTP 415 hatasını çözerken en sağlıklı yöntem, aynı anda birkaç ayarı değiştirmek yerine her denemede yalnızca bir alanı düzeltmektir. Böylece hatanın hangi değişiklikten sonra ortadan kalktığını görebilirsin. Aşağıdaki örnekte kullanılan uç nokta temsili bir API adresidir; gerçek yanıt kodu, yanıt gövdesi ve kabul edilen medya türleri yayımdan önce ilgili API dokümantasyonundan doğrulanmalıdır.

1. Hatalı isteği kaydet

İlk istekte gövde JSON biçimine benziyor ancak Content-Type başlığı gönderilmiyor:

POST /api/ornek-kayit

{
  "name": "Ada",
  "age": 20,
}

Bu istekte sunucu, gövdeyi hangi ayrıştırıcıyla okuyacağını kesin olarak belirleyemeyebilir. Beklenen sonuç, genelleştirilmiş olarak şöyle olabilir:

{
  "status": 415,
  "error": "Unsupported Media Type"
}

Gerçek API, hata gövdesini farklı alanlarla döndürebilir veya yalnızca durum kodu gönderebilir.

2. Yalnızca Content-Type başlığını ekle

İlk değişiklikte gövdeye dokunmadan yalnızca başlığı ekle:

Content-Type: application/json

{
  "name": "Ada",
  "age": 20,
}

Bu kez sunucu, isteği JSON olarak ayrıştırmayı deneyebilir. Ancak gövdede son elemandan sonra virgül bulunduğu için geçerli JSON oluşmaz. Bu durumda 415 yerine 400 benzeri bir ayrıştırma hatası alınması mümkündür. Durum kodu ve yanıt biçimi kullanılan API’ye göre değişir.

3. Gövdeyi Content-Type değeriyle eşleştir

Content-Type: application/json kullanıyorsan gövdenin tamamı geçerli JSON olmalıdır. Form verisi, düz metin veya Python sözlüğünün doğrudan yazdırılmış hâli JSON yerine kullanılamaz. Örneğin aşağıdaki gövde JSON biçimine yakındır ancak henüz sözdizimsel olarak geçerli değildir:

{
  "name": "Ada",
  "age": 20,
}

Bu adımda yalnızca gövde biçimini kontrol et. Anahtarların çift tırnak içinde olması, değerlerin doğru türde bulunması ve nesnenin süslü parantezlerle kapanması gerekir.

4. JSON sözdizimini düzelt

Son elemandan sonra gelen virgülü kaldırarak geçerli JSON gönder:

POST /api/ornek-kayit
Content-Type: application/json

{
  "name": "Ada",
  "age": 20
}

Sunucu medya türünü destekliyor ve gerekli alanları bekliyorsa genelleştirilmiş bir başarı yanıtı şu yapıda olabilir:

{
  "id": 123,
  "status": "created"
}

Buradaki id, status ve diğer yanıt alanları yalnızca örnektir; gerçek API’nin yanıt şeması farklı olabilir.

5. Accept değerini yalnızca yanıt beklentisi için değerlendir

Accept başlığı, istemcinin hangi yanıt medya türünü tercih ettiğini belirtir:

Accept: application/json

Bu başlık, gönderdiğin istek gövdesinin türünü belirlemez. İstek gövdesi için Content-Type, beklenen yanıt için Accept kullanılır. Bu nedenle yalnızca Accept değerini değiştirmek çoğu 415 hatasını çözmez. Önce gönderilen gövdenin Content-Type ile uyumlu olduğundan emin ol.

Aynı tek değişiklik yaklaşımını Postman, Python veya Java istemcisinde de uygulayabilirsin. İstemci tarafındaki başlık ve gövde düzeltmelerinden sonra sunucu parser’ının isteği okuyup okuyamadığını kontrol et. Parser gövdeyi okuyamıyorsa medya türü desteği, gövde kodlaması veya sunucu yapılandırması incelenmelidir. İsteklerin adım adım izlenmesi ve tekrar incelenebilmesi için tekrar izlenebilen video eğitimler yararlı bir çalışma desteği sağlayabilir.

HTTP 415 İçin Son Kontrol Listesi ve Sonraki Adım

• Endpoint adresinin doğru olduğundan emin ol.
• HTTP metodunun API dokümantasyonundaki yöntemle aynı olduğunu kontrol et.
• Content-Type değerinin gönderilen gövdeyle uyumlu olduğunu doğrula.
• JSON gönderiyorsan JSON sözdiziminin geçerli olduğunu kontrol et.
• Accept başlığının yalnızca beklediğin yanıt türünü ifade ettiğini unutma.
• Sunucu parser’ının kullandığın medya türünü ayrıştırabildiğini incele.

Her değişiklikten sonra isteği yeniden gönder ve sonucu kaydet. Bir denemede hem başlığı hem gövdeyi hem de endpoint’i değiştirme; aksi hâlde hangi düzeltmenin etkili olduğunu anlayamazsın. Makalede kullanılan örnek API’nin dokümantasyon bağlantısı ve test ortamı da yayımdan önce kontrol edilmelidir.

HTTP isteklerini öğrenirken yalnızca hata mesajını ezberlemek yerine başlık, gövde ve sunucu parser’ı arasındaki ilişkiyi kurmaya çalış. API öğrenme sürecinde yeni teknik yazıları ve uygulamalı anlatımları Berk Akademi blog arşivi üzerinden takip edebilirsin.

Sık Sorulan Sorular

Content-Type ile Accept arasındaki temel fark nedir?

Content-Type, istemcinin sunucuya gönderdiği istek gövdesinin türünü belirtir. Accept ise istemcinin sunucudan almak istediği yanıt türünü ifade eder. JSON gönderirken genellikle Content-Type: application/json kullanılır; JSON yanıt bekleniyorsa ayrıca Accept: application/json belirtilebilir.

application/json gönderirken Content-Type başlığı neden gereklidir?

Sunucu, istek gövdesini hangi parser ile okuyacağını bu başlığa göre belirleyebilir. Başlık eksikse veya farklı bir medya türü belirtilmişse sunucu JSON gövdesini kabul etmeyerek HTTP 415 döndürebilir.

Postman’da JSON seçili olduğu hâlde neden HTTP 415 hatası alınabilir?

Postman’daki gövde seçimi, gönderilen isteğin her ayrıntısının doğru olduğu anlamına gelmez. Başlığın gerçekten application/json olarak gönderildiğini, gövdenin geçerli JSON olduğunu ve endpoint’in bu medya türünü kabul ettiğini ayrıca kontrol etmelisin.

HTTP 415 hatasında sunucu parser’ı nasıl kontrol edilir?

Önce istemciden doğru Content-Type ile geçerli bir gövde gönderildiğini doğrula. Hata devam ediyorsa sunucunun ilgili medya türü için parser desteğini, gövde okuma yapılandırmasını ve API dokümantasyonundaki kabul edilen içerik türlerini incele. Bu ayrıntılar her framework ve API’de aynı şekilde çalışmayabilir.

Yazar: eğitmenimiz Berk Keskin