HTTP 415: Porozumění a řešení chyby Unsupported Media Type v praxi

Co znamená HTTP 415 a kdy se objevuje

HTTP 415, neboli HTTP 415 Unsupported Media Type, je chybový kód odpovědi, který server vrací tehdy, když požadavek obsahuje tělo, které server neumí zpracovat vzhledem k uvedenému Content-Type nebo k formátu samotného obsahu. V praxi se tato situace nejčastěji objevuje u REST API, kde klient posílá data v určitém médiu (například application/json, application/xml, multipart/form-data apod.), ale server očekává jiný formát nebo je obsah poškozený. Správně nastavený Content-Type a konzistentní tělo požadavku jsou klíčové pro hladký průběh komunikace mezi klientem a serverem.

Definice a kontext

Chybový kód HTTP 415 signalizuje, že médium, které je uvedeno v hlavičce Content-Type, není podporované nebo odpovídající formát těla požadavku. Někdy se v praxi setkáme i s tím, že server vyžaduje specifický formát, například JSON, a vy přijímáte jiné mediální typy nebo tělo neodpovídá popisu v dokumentaci. Důležité je pochopit, že Content-Type je ručník, který říká serveru, jaký „jazyk“ používáte pro komunikaci s API, a pokud se s ní nezachází konzistentně, přijde právě HTTP 415.

Typické příčiny HTTP 415

Neplatný Content-Type

• Nesprávně uvedený médiový typ v hlavičce Content-Type, který neodpovídá skutečnému tělu požadavku.
• Chybějící Content-Type u požadavků, které mají tělo (například POST odeslaný bez hlavičky Content-Type).
• Použití obecného médiového typu, který server neposkytuje dostatečné instrukce o struktuře dat (např. application/octet-stream bez interpretovatelného obsahu).

Nesoulad těla požadavku s uvedeným médiem

• Posíláte JSON (application/json), ale tělo není validní JSON (chybná syntaktická struktura, chybějící závorky, neuzavřené řetězce).
• Posíláte XML (application/xml) a dokument není platný XML (chyby v uzavírání tagů, neuzavřené elementy).
• Binary data reprezentujete jako JSON nebo text a tím porušíte očekávanou strukturu.

Verze API a změny formátu

• Novější verze API mohou vyžadovat odlišný Content-Type nebo novou strukturu databázových entit. Pokud klient zůstane na starém formátu, server odpoví HTTP 415.
• Rozšíření nebo změna schématu dat bez aktualizace dokumentace vede ke konfliktům mezi očekáváním serveru a poskytovaným obsahem.

Jak HTTP 415 ovlivňuje vývoj a integraci

Dopad na komunikaci API

Když se objeví HTTP 415, znamená to, že část komunikace mezi klientem a serverem není sladěná. Vývojáři musí řešit, jak správně vyargumentovat typ obsahu, a jak zajistit, že nejen hlavička Content-Type, ale i samotné tělo požadavku odpovídá očekávané struktuře. To má vliv na návrh API, testování a automatizované testy.

Bezpečnostní a provozní souvislosti

Chyba 415 může být zneužita nekvalitně definovanými koncovými body pro expozici dat. Správné používání Content-Type napomáhá zlepšit ochranu dat a snížit rizika špatné interpretace obsahu napříč systémy. Z hlediska provozu je důležité, aby logy obsahovaly jasný záznam o tom, které konkrétní hodnoty Content-Type a těla požadavku vyvolaly HTTP 415, což usnadní debugging a opravu.

Jak řešit HTTP 415 v praxi

Kontrola a ladění na straně klienta

• Ujistěte se, že Content-Type odpovídá formátu těla požadavku. Pokud odesíláte JSON, použijte application/json a ověřte platnost JSON (např. syntaktickou validaci).
• Ověřte, že tělo skutečně odpovídá struktuře definované v API dokumentaci. Pro JSON to bývá prázdná mapa {}, pole, položky se správnými klíči.
• Pro testy použijte nástroje jako curl nebo Postman a vyzkoušejte různé kombinace Content-Type a těla, abyste zjistili, kde nastává konflikt.

Kontrola na straně serveru

• Ověřte, že server skutečně podporuje požadované médium a že jeho parsovací modul správně zpracovává daný typ obsahu.
• Pro vývojáře API zvažte explicitní validaci vstupu: pokud přijmete Content-Type, zkontrolujte i spoluodpovídající šablonu a odpověď s detailní informace o tom, proč je obsah neplatný.
• Poskytněte jasnou a konzistentní dokumentaci o tom, jaké typy obsahu API očekává a jaké jsou požadavky na tělo požadavku.

Testování a nástroje

Rychlá identifikace HTTP 415 často spočívá v použití správných testovacích nástrojů. Doporučuji:

• curl: vyzkoušet různé Content-Type a těla; např. curl -X POST -H "Content-Type: application/json" -d '{"name":"Jan"}' https://api.example.com/user
• Postman nebo Insomnia: jednoduché UI pro testování různých médií a sledování odpovědí serveru.
• Validace šablon: pro JSON použijte validátory JSON, pro XML validátory XML a pro multipart testy zkontrolujte strukturu formulářů.

Vhodná nastavení a best practices pro HTTP 415

Správné používání Content-Type a Accept

• Content-Type by měl přesně definovat formát těla požadavku, který posíláte. Pokud server očekává JSON, použijte application/json.
• Accept: pokud očekáváte odpověď ve specifickém formátu, určete jej v hlavičce Accept (např. Accept: application/json).
• Neodstraňujte hlavičky a neukončujte požadavky neúplnými informacemi – konzistentnost je klíčová.

Preferování content negotiation

• V ideálním světě API podporuje více formátů a výběr se řídí content negotiation: klient uvede svůj preferovaný formát a server mu odpoví nejlépe dostupným způsobem.
• Pro robustní API je vhodné explicitně ošetřit situace, kdy neposkytnete JSON i přes existenci fallbacků – server by měl jasně upozornit na to, proč HTTP 415 nastal a jaké řešení je akceptovatelné.

HTTP 415 v praxi: příklady z reálného světa

V různých kontextech se HTTP 415 může objevit různě. Níže jsou uvedeny typické scénáře, které se často opakují v plném provozu:

• Upload souborů přes API: klient zasílá multipart/form-data, ale server očekává application/octet-stream pro binární data a v těle chybí správný boundary nebo form-data pole.
• API pro vytvoření zdroje: dolní vrstvy API vyžadují JSON, ale klient posílá XML; server vrací HTTP 415 s popisem, že očekává application/json.
• Webhooks a integrace: systém posílá webhook s Content-Type, který nebyl v konfiguraci povolen, což v konečném důsledku vyvolá HTTP 415 na přijímajícím end-pointu.

Často kladené otázky o HTTP 415

Co znamená HTTP 415?

HTTP 415 znamená, že zaslané médium (Content-Type) není podporované nebo neodpovídá tělu požadavku. Je to signál, že je třeba sjednotit formát dat mezi klientem a serverem nebo přizpůsobit parsování na straně serveru.

Jak opravit HTTP 415 na klientu?

• Zkontrolujte, že Content-Type odpovídá skutečnému formátu těla požadavku.
• Ověřte platnost a strukturu těla (např. validita JSON/XML).
• Podívejte se do dokumentace API, zda podporuje požadovaný formát a zda jsou vyžadovány specifické verze médií.

Jak se liší HTTP 415 od 400?

Oba kódy patří do třídy klientských chyb, ale HTTP 400 (Bad Request) signalizuje obecně špatný požadavek, zatímco HTTP 415 specificky označuje problém s médiem / formátem obsahu. Pokud je problém v obsahu, který se nedá zpracovat kvůli mediálnímu typu, je HTTP 415 vhodnější popis situace.

Závěr: HTTP 415 jako signál pro lepší návrh API

Chybový kód HTTP 415 často funguje jako užitečný signál pro vývojáře – ukazuje, že je třeba jasně definovat a dokumentovat, jaké typy obsahu API očekává, a jaké formáty jsou akceptovatelné. Správně navržené strategie Content-Type a content negotiation vedou k lepší spolehlivosti, rychlejšímu debuggingu a vyšší interoperability mezi různými systémy. Při dodržení osvědčených postupů a důsledné validaci na obou stranách se HTTP 415 stane užitečným nástrojem, nikoliv překážkou.

Praktické shrnutí do tří kroků

• Jasně definujte médium: vždy uvádějte správný Content-Type a ověřte jeho kompatibilitu s tělem požadavku.
• Validujte data: zkontrolujte syntaxi a strukturu na klientovi i serveru; používejte validátory a testy.
• Dokumentujte a testujte: uveďte očekávané typy obsahu v dokumentaci API a pravidelně provádějte end-to-end testy s různými scénáři.