HTTP 415: De ultieme gids over Unsupported Media Type en hoe je het efficiënt oplost

Eigenaar Programmeerwerk en frameworks 19. september 2025 | 0

In de wereld van webontwikkeling en API-communicatie kom je regelmatig foutcodes tegen die de interactie tussen client en server regelen. Een van de meest besproken en soms verwarrende is HTTP 415. Deze foutcode duidt op een probleem met het bericht dat de client naar de server stuurt: het media-type, oftewel het Content-Type van de payload, wordt door de server niet ondersteund of begrepen. In dit artikel duiken we diep in wat HTTP 415 inhoudt, hoe het ontstaat, welke contexten relevant zijn en wat je praktisch kunt doen om het op te lossen. We spreken over http 415 en HTTP 415 in diverse varianten, zodat je dit foutbeeld in verschillende stacktraces en logs meteen herkent.

Wat is http 415 precies?

http 415, of voluit HTTP 415 Unsupported Media Type, is een statuscode die door een server wordt teruggegeven als het aangekoppelde payload-formaat niet wordt herkend of niet wordt ondersteund. Dit gebeurt meestal wanneer de client een Content-Type meestuurt dat de server niet kan ontleden, of wanneer de payload niet overeenkomt met wat de server verwacht op basis van de API specificatie of het ingestelde Content-Type. In de praktijk gaat het dus om een mismatch tussen wat verzonden wordt en wat de server accepteert.

HTTP 415 versus http 415: verschil in notatie

Je zult zowel HTTP 415 als http 415 tegenkomen in documentatie en logs. In technisch jargon verwijst HTTP naar het protocol, terwijl de informele afkorting http 415 nog steeds breed wordt gebruikt in gesprekken en handleidingen. Voor SEO-doeleinden en duidelijke communicatie is het verstandig om beide vormen te herkennen en te herhalen in je eigen documentatie of blogs, maar altijd duidelijk te zijn wanneer je spreekt over HTTP 415 als officiële term en http 415 als informele verwijzing.

De fout 415 ontstaat wanneer de server het ingestuurde bericht niet kan verwerken vanwege een niet-ondersteund of niet-herkenbaar media-type. Hieronder enkele veelvoorkomende oorzaken die in practice vaak voorkomen:

Oorzaken gerelateerd aan de Content-Type header

De Content-Type header ontbreekt terwijl de server een bepaald formaat verwacht (bijvoorbeeld JSON of XML).
Het Content-Type geeft een formaat aan dat de server niet ondersteunt (bijv. application/x-yaml terwijl de API alleen JSON accepteert).
Het Content-Type komt overeen met een formaat, maar de payload zelf is niet geldig volgens dat formaat (bijv. ongeldige JSON-syntaxis).

Mismatch tussen payload en API-specificaties

De API vereist JSON, maar de payload is URL-encoded data (application/x-www-form-urlencoded).
Een multipart/form-data payload bevat een ontbrekende of onjuiste boundary-scheiding, waardoor de server de onderdelen niet correct kan parsen.
Een webhook of API-call stuurt binary data terwijl de server verwacht tekstuele JSON of XML.

Fout in de client-side tooling

Een generator of SDK die onjuiste Content-Type headers toevoegt bij de request payloads.
Ontwikkel- of testtools die de payload niet correct serialiseren, waardoor de server een ongeldig bericht ontvangt met een ogenschijnlijk correct Content-Type.

Versies en transformatietoleranties

Bij API-versies kunnen oudere servers strenger zijn wat betreft media-types; wat in een oudere versie werkt, kan in een nieuwere versie leiden tot HTTP 415 als het verstuurde formaat niet meer wordt ondersteund.
Bij transformaties zoals compressie (bijv. gzip) kan de server verwachten dat de payload op een bepaalde manier werd geleverd, en afwijkingen leiden tot 415.

Het is vaak verhelderend om concrete scenario’s te bekijken waarin HTTP 415 verschijnt. Hieronder enkele realistische voorbeelden met korte uitleg over wat er mis ging en hoe je het oplost.

Voorbeeld 1: API-call met JSON-verwachting maar formulier-data verzonden

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json

<{ "name": "Ana", "email": "ana@example.com" }>

In dit scenario verwacht de API JSON, maar de payload is correct geformatteerd JSON. Echter, sommige frameworks kunnen extra headers vereisen of een specifieke structuur. Als de server een 415 teruggeeft, kan het zijn dat de server JSON verwacht, maar de payload is een string-achtig object of de server vereist een batched payload. Controleer zowel Content-Type als payload-inhoud en vergelijk met de API-specificatie.

Voorbeeld 2: Onbekende Content-Type bij Multipart-uploads

POST /api/upload HTTP/1.1
Host: api.example.com
Content-Type: application/form-data; boundary=BOUNDARY

De juiste Content-Type voor bestandsuploads is meestal multipart/form-data met een correcte boundary. Als de server echter een andere boundary heeft verwacht of de boundary-definitie ontbreekt, kan HTTP 415 optreden. Controleer de boundary-scheiding en het feit of de payload alle delen bevat zoals de API-documentatie voorschrijft.

Voorbeeld 3: Verkeerd Content-Type bij XML-API

POST /api/transactions XML/1.0

<transaction>...</transaction>

Wanneer een API XML vereist, maar de header en de payload niet overeenkomen (bijv. Content-Type: application/xml maar de payload is niet goed ge-xml-wrapped), kan HTTP 415 verschijnen. Zorg ervoor dat het Content-Type juist is en de payload volgens de XML-schema’s of DTD’s is getoond.

Of je nu een Node.js-backend, een Java/Spring-stack, .NET, of een PHP-omgeving gebruikt, de basisprincipes blijven hetzelfde: het media-type van de payload moet overeenkomen met wat de server accepteert. Toch zijn er stack-specifieke valkuilen die je kent als ontwikkelaar:

Node.js en Express

In Express is het gebruikelijk om body-parsers te configureren die afhankelijk zijn van Content-Type. Verkeerde of ontbrekende middleware kan leiden tot 415 wanneer de server probeert het bericht te parse zonder de juiste parser. Controleer de installatie van body-parser (of de ingebouwde Express 4.16+ parsers) en zorg voor consistente Content-Type header in requests en correct afhandeling in de route handlers.

Java en Spring

In Spring Boot kun je via @RequestBody en produces/consumes in @RequestMapping aangeven welke media-types geaccepteerd worden. Een mismatch tussen consumes en de ingestuurde Content-Type leidt soms tot 415. Zorg ervoor dat de controller-annotaties overeenkomen met wat je API ondersteunt, en overweeg de implementatie van HttpMessageConverters die het juiste formaat kunnen parsen.

.NET en ASP.NET Core

In ASP.NET Core kun je modelbinding en formatter pipelines hebben die alleen bepaalde media-types accepteren. Controleer de ConfigureServices en de middleware-pijplijn om te verzekeren dat JSON, XML, of andere formats correct zijn geconfigureerd en dat de Content-Type header op de client-side overeenkomt met wat de server verwacht.

PHP en Laravel

Laravel en andere PHP-frameworks hangen af van de PHP-extensies en de Content-Type header om de payload te parsen. Een ontbrekende of foutieve Content-Type kan leiden tot HTTP 415. Controleer de controllers, de request validation en de aanwezigheid van juiste middleware voor content negotiation.

Een gestructureerde aanpak verkort de tijd tot oplossing aanzienlijk. Hieronder een stappenplan dat je direct kunt toepassen wanneer je HTTP 415 ziet.

Stap 1: Controleer de Content-Type header

Vraag eerst aan de client wat Exact Content-Type werd meegestuurd. Vergelijk dit met wat de API-specs aangeven. Als Content-Type ontbreekt, voeg het toe. Als het onjuist is, corrigeer het en verstuur de request opnieuw. Let ook op tool-specifieke gedrag, zoals curl, Postman of Insomnia die soms standaard Content-Type opgeeft.

Stap 2: Controleer het payload-formaat

Controleer of de payload daadwerkelijk voldoet aan het media-type dat werd opgegeven. Bij JSON: valideer met een JSON-validator. Voor XML: controleer op goedXML en geldige structuren. Voor multipart: check de boundaries en elk part-veld. Een ongeldige payload kan ook al leiden tot de indruk van een 415, terwijl de onderliggende fouttekst elders ligt.

Stap 3: Controleer server-side configuratie en formatter-pipelines

Bekijk welke formatteren de server ondersteunt en of er conflicterende configuraties bestaan. Soms accepteert de server JSON maar wordt een speciale variant verwacht, bijvoorbeeld een aangepaste content-type voor een eigen API. Controleer de lijst van HttpMessageConverters of eigen parsers en pas ze aan indien nodig.

Stap 4: Test met bekende-good-merk payloads en endpoints

Maak testgevallen met bekende, goedgedefinieerde payloads voor de API en test op verschillende Content-Types. Gebruik bijvoorbeeld een minimale JSON payload voor een gebruikersaanmaak en kijk of 200/201 terugkomt. Als 415 blijft terugkomen, is de mismatch waarschijnlijk tussen type en payloadstructuur, niet de payload zelf.

Stap 5: Logboek en tracing toevoegen

Voeg logging toe rond de lees- en parse-stappen, inclusief de ontvangen Content-Type en de eerste regels van de payload (indien veilig). Als je tracing hebt, voeg spans toe bij de parser/serializer-fase zodat je precies ziet waar het misgaat.

Naast het oplossen van HTTP 415, kun je best practices volgen om soortgelijke problemen in de toekomst te voorkomen. Hieronder vind je een reeks concrete aanbevelingen die direct toepasbaar zijn in moderne ontwikkelomgevingen.

Definieer duidelijk welke media-types worden ondersteund

Specificeer exact welke Content-Types geaccepteerd worden in de API-documentatie (bijv. application/json, application/xml, multipart/form-data).
Beperk het aantal ondersteunde types tot wat actually nodig is, zodat clients die types niet ervaren niet op 415 stuiten.

Implementeer duidelijke foutberichten

Geef in HTTP 415-responses duidelijke meldingen terug die aangeven welk Content-Type werd verwacht en wat er misging bij de payload.
Voeg eventueel hints toe, zoals “Controleer de Content-Type header en het payload-formaat.”

Automatiseer tests voor content negotiation

Schrijf tests die verschillende Content-Type combinaties dekken en controleer of de server correct reageert.
Voeg regresstests toe zodat toekomstige wijzigingen niet leiden tot onbedoelde 415-varianten.

Gebruik duidelijke API-contracten

Maak gebruik van OpenAPI (Swagger) specificaties die exact aangeven welke media-types ondersteund worden.
Laat automatische clientgeneratie aansluiten op deze contracten, zodat client-code consistent blijft met de API.

HTTP 415 onderscheidt zich van andere veelvoorkomende foutcodes door te focussen op de inhoud van de payload in relatie tot de verwachte media-type. Hier een snelle vergelijking met andere gerelateerde codes:

400 Bad Request: algemene fout bij een ongeldige aanvraag. Een HTTP 415 kan als specifieke oorzaak 400 volgen; 415 zelf geeft aan dat het issue bij het content-type ligt.

415 Unsupported Media Type: specifiek de foutcode die aangeeft dat het bericht niet het juiste type heeft voor de beoogde verwerking.

406 Not Acceptable: betreft negotie in de response, niet de request payload; het is gerelateerd maar heeft een andere focus.

415 en Content-Type mismatches: 415 is vaak het gevolg van een mismatch tussen Content-Type en payload-structuur.

Er bestaan tal van praktische hulpmiddelen waarmee je HTTP 415 kunt reproduceren, controleren en oplossen. Hieronder een selectie van favoriete tools onder ontwikkelaars in Vlaanderen en de bredere Belgische techgemeenschap.

Postman en Insomnia

Beide toolsets bieden grafische interfaces om Content-Type headers, payloads en endpoints eenvoudig te manipuleren. Gebruik test suites die verschillende media-types inzetten, zodat je snel ziet bij welk type de server een 415 teruggeeft.

cURL en HTTPie

Voor snelle scripten en commandline testing zijn curl en HTTPie onmisbaar. Voorbeeld curl:

curl -X POST https://api.example.com/api/users -H "Content-Type: application/json" -d '{ "name": "Sophie" }'

Met HTTPie kun je meer expressieve commando’s geven en direct zien wat er misgaat bij de server.

Browser Developer Tools

Voor front-end issues zijn browser devtools handig om te inspecteren welke Content-Type de browser verstuurt en wat de response header-informatie zegt. Dit helpt vooral bij debuggen van webapplicaties die REST-API’s aanroepen.

Monitoring en logging

Integreer log- en tracing-tools zoals ELK/EFK-stacks, Jaeger of OpenTelemetry om HTTP 415-traces te volgen en patronen te ontdekken in mislukte verzoeken.

Een proactieve aanpak kan veel HTTP 415-issues voorkomen. Hier zijn enkele ontwerpprincipes die je kunnen helpen bij API-ontwikkeling.

Content negotiation en duidelijke contracten

Implementeer een duidelijke content negotiation-strategie op serverniveau zodat clients expliciet kunnen kiezen uit ondersteunde media-types via Accept- en Content-Type-header.
Documenteer welke types je API accepteert en welke types geaccepteerd zijn voor responses.

Validatie op payload-niveau

Voer vroege payload-validatie uit voordat je probeert te parsen. Dit voorkomt onnodige parsing-fouten en laat je betere foutmeldingen achter.
Valideer alleen de structuur van de payload en niet de inhoud van de payload die per se leesbaar moet zijn; dit maakt debugging eenvoudiger.

Consistente serializer/serializer-keuzes

Kies één set van serializer-formatters per endpoint en zorg voor consistentie. Vermijd het toestaan van meerdere gelijktijdige formaten zonder duidelijke regels.
Test end-to-end met de gekozen serializer-pipelines in CI/CD-omgevingen.

Er bestaan meerdere misverstanden die leiden tot onnodige frustratie bij developers. We pakken de belangrijkste aan en geven ondersteunde uitleg.

“Het is altijd de client die faalt”

Hoewel HTTP 415 een clientgerichte fout is, kan de server-instelling of API-specificatie ook onbedoeld verkeerd zijn. Het is essentieel om samen met de API-eigenaar te controleren of de clientverwachtingen en serverconfiguraties nog op elkaar zijn afgestemd.

“Elke onjuiste payload levert 415 op”

Niet elke fout in payload leidt tot 415. Soms kan een 400 of 422 (Unprocessable Entity) meer geschikt zijn. 415 wijst specifiek op het media-type, niet op de algebrische validatie van inhoud.

“HTTP 415 is zeldzaam”

In moderne API-architecturen komt HTTP 415 relatief vaak voor wanneer developers verschillende clients en payloaden ondersteunen, zeker bij API’s die content negotiation en meerdere formats aanbieden.

HTTP 415 is meer dan een foutmelding; het is een signaal dat de interactie tussen client en server goed gedefinieerd moet zijn. Door duidelijke contracten, consistente payload-validatie en gerichte debugging kun je niet alleen het probleem snel oplossen maar ook de robuustheid van je API verhogen. Door http 415 en HTTP 415 consequent te herkennen in logs, promoot je betere ontwikkeling, testpraktijken en klanten die jouw API vol vertrouwen kunnen gebruiken. Met de juiste tooling en een doordachte aanpak kun je dit veelvoorkomende obstakel omarmen als een kans om jouw API’s betrouwbaarder en gemakkelijker te debuggen te maken.

Controleer altijd de Content-Type header die meegestuurd wordt en vergelijk die met wat de API accepteert.

Valideer de payload tegen het aangegeven formaat (JSON, XML, YAML, etc.).

Verifiëer de serverconfiguratie: welke media-types ondersteunt de API?

Test met voorbeeldpayloads en verschillende content-types in een geïntegreerde testomgeving.

Gebruik duidelijke foutberichten in HTTP 415-responses zodat eindgebruikers en developers weten wat er misging en wat te doen.

Documenteer media-type-ondersteuning in OpenAPI of vergelijkbare contracten en houd ze up-to-date.

Met deze inzichten kun je niet alleen HTTP 415 sneller identificeren en oplossen, maar ook proactief werken aan betere API-ontwerpen die bestand zijn tegen de veelzijdigheid van moderne client-apps. Of je nu een frontend-, mobiel- of backend-ontwikkelaar bent, het begrijpen en beheersen van http 415 levert directe voordelen op in betrouwbaarheid, performance en gebruiksvriendelijkheid van jouw digitale diensten.

Wil je verder duiken in gerelateerde HTTP-statuscodes en content negotiation? Overweeg om OpenAPI-specifications te raadplegen, documentatie van populaire web-frameworks te bekijken en je testcases uit te breiden met gevarieerde payloads. Het pad naar stabiele, robuuste API’s ligt in consistentie, duidelijke contracten en grondige testing—precies de ingrediënten die HTTP 415 in een waardevol hulpmiddel kunnen omzetten in plaats van een frustratie.