L’errore 415 Unsupported Media Type indica che il server rifiuta il formato del corpo inviato. Il client può dichiarare un Content-Type non supportato, inviare dati che non corrispondono all’header oppure omettere informazioni necessarie come il boundary multipart.
Questa guida approfondisce errore 415 Unsupported Media Type con verifiche progressive e reversibili. Non inviare password, cookie, token, chiavi private, codici 2FA o file di configurazione completi nei ticket.
Che cosa significa
Il codice riguarda il contenuto della richiesta, mentre il 406 riguarda normalmente il formato accettabile della risposta. Nelle API la distinzione tra Accept e Content-Type è fondamentale.
Cambiare soltanto l’estensione del file non modifica il tipo effettivo. Il server o l’applicazione può controllare MIME type, firma binaria e struttura del payload.
Come riconoscere il problema
- Una API accetta JSON ma rifiuta form-data.
- L’upload fallisce soltanto per alcuni formati.
- Il client invia Content-Type application/json ma il corpo non è JSON.
- Una richiesta multipart non contiene boundary.
- Il browser funziona mentre uno script personalizzato riceve 415.
Cause più frequenti
1. Content-Type errato
L’header non descrive il corpo reale. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.
2. Formato non previsto dall’endpoint
L’API accetta soltanto JSON, XML o multipart specifico. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.
3. Boundary multipart mancante
Il client costruisce manualmente un header incompleto. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.
4. Charset o codifica
Il server non supporta la variante dichiarata. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.
5. MIME file non consentito
WordPress o il plugin limita i tipi caricabili. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.
6. WAF o gateway API
Un livello intermedio applica una policy sui media type. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.
Diagnosi passo per passo
- Leggi la documentazione dell’endpoint. Identifica media type e schema richiesti. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
- Confronta Content-Type e corpo. Verifica byte e struttura effettiva. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
- Controlla Accept separatamente. Non confondere richiesta e risposta. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
- Lascia generare il boundary al client. Non impostare manualmente multipart quando la libreria lo gestisce. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
- Riduci il payload. Invia un esempio minimo valido. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
- Controlla log applicativi e WAF. Cerca unsupported media type e rule id. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
- Confronta la richiesta funzionante. Esporta cURL dal browser o dal client ufficiale senza includere token. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
Metodo sicuro di diagnosi
Prima di modificare la configurazione, registra URL o servizio coinvolto, messaggio completo, data e ora, ultima modifica nota, client o rete e risultato ottenuto con un secondo strumento. Questa fotografia iniziale permette di confrontare i test e di tornare alla configurazione precedente quando una modifica non produce il risultato atteso.
Applica una sola correzione alla volta. Dopo ogni intervento ripeti esattamente la stessa operazione e controlla i log dello stesso intervallo temporale. Modificare contemporaneamente DNS, cache, PHP, plugin, proxy e firewall elimina la possibilità di attribuire il risultato a una causa precisa.
Controllo incrociato
Usa almeno due fonti indipendenti. Per HTTP confronta browser, curl e log; per WordPress confronta frontend, wp-admin, Site Health e WP-CLI; per DNS interroga nameserver autoritativi e resolver pubblici; per la posta confronta Webmail, intestazioni originali e Track Delivery. Cache, TTL e code possono mostrare stati differenti per alcuni minuti.
Quando il problema sembra risolto, esegui una seconda prova con una nuova sessione, un secondo utente o una seconda rete quando applicabile. Verifica inoltre che TLS, autenticazione, WAF, permessi e controlli antispam restino attivi: una correzione che disabilita stabilmente le protezioni non è una soluzione definitiva.
Verifica prolungata dopo la correzione
Conserva temporaneamente backup, valori precedenti ed estratti dei log. Ripeti il controllo dopo il normale ciclo di cache, cron, coda o TTL. Se l’anomalia ricompare a intervalli regolari, confronta l’orario con backup, aggiornamenti, rinnovi SSL, rotazioni DNS, processi pianificati e servizi esterni.
Documenta il risultato finale con data, comando o schermata utilizzata e condizione verificata. Questa nota evita interventi duplicati e rende più rapida una futura analisi da parte dell’assistenza.
Procedura di risoluzione
- Imposta il Content-Type corretto. Per esempio application/json con JSON valido. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
- Usa il metodo previsto. Alcuni endpoint accettano media type diversi per POST e PUT. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
- Correggi multipart/form-data. Affida boundary e codifica alla libreria. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
- Convalida il file. Usa estensione e contenuto realmente supportati. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
- Aggiorna plugin o client API. Versioni vecchie possono inviare header incompatibili. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
- Configura una eccezione mirata. Solo se il WAF blocca un formato legittimo documentato. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
- Ritesta con un payload minimo. Aggiungi poi i campi uno alla volta. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
Come raccogliere prove utili
Quando riproduci il problema, conserva soltanto i dati tecnici necessari: codice di risposta, URL priva di token, orario con fuso, request ID, nome del client, dimensione del file o del messaggio e una breve descrizione dell’operazione. Evita screenshot parziali quando puoi esportare il testo originale, perché header, log e messaggi completi permettono una diagnosi più precisa.
Prima di chiudere il controllo, confronta il comportamento con una configurazione nota e funzionante. Per una API usa un payload minimo; per WordPress prova una funzione core senza plugin aggiuntivi; per DNS interroga direttamente i nameserver; per la posta usa Webmail e conserva il file `.eml`. Questo confronto riduce le ipotesi e impedisce modifiche inutili.
Controlli finali
- Content-Type descrive il corpo.
- L’endpoint accetta il payload.
- File e MIME coincidono.
- Il WAF resta attivo.
- Nessun dato sensibile è presente nei log condivisi.
Prevenzione
- Contratti API documentati.
- Test automatici.
- Librerie aggiornate.
- Convalida MIME.
- Payload minimi.
Errori da evitare
- Non usare application/json per dati non JSON.
- Non impostare boundary casuali.
- Non rinominare soltanto l’estensione.
- Non disattivare il WAF globalmente.
- Non confondere 415 e 406.
Quando contattare l’assistenza Xlogic
Apri un ticket quando il problema persiste dopo i controlli di base, coinvolge più servizi oppure richiede log e configurazioni non disponibili nel pannello. Indica:
- endpoint e metodo
- Content-Type e Accept
- payload minimo oscurato
- orario
- risposta e log
Non inviare credenziali. URL, orari, codici, header non sensibili e messaggi di errore sono sufficienti per iniziare la diagnosi.
Fonti tecniche ufficiali
Domande frequenti su errore 415 Unsupported Media Type
Qual è la differenza tra 415 e 406?
Il 415 riguarda il corpo inviato; il 406 il formato della risposta richiesta.
Devo impostare manualmente il boundary?
Normalmente no, la libreria multipart lo genera correttamente.
Cambiare estensione risolve il MIME?
No, il contenuto reale può essere ancora non supportato.
Un plugin WordPress può restituire 415?
Sì, soprattutto negli endpoint REST o negli upload personalizzati.
Che cosa devo confrontare?
Metodo, Content-Type, Accept e corpo della richiesta funzionante e fallita.