Errore 415 Unsupported Media Type: API e upload

In breve: Errore 415 Unsupported Media Type: API e upload: L’errore 415 Unsupported Media Type indica che il server rifiuta il formato del corpo inviato.

Errore 415 Unsupported Media Type: API e upload

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.

3. Boundary multipart mancante

Il client costruisce manualmente un header incompleto.

4. Charset o codifica

Il server non supporta la variante dichiarata.

5. MIME file non consentito

WordPress o il plugin limita i tipi caricabili.

6. WAF o gateway API

Un livello intermedio applica una policy sui media type.

Diagnosi passo per passo

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.

Procedura di risoluzione

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.

Domande frequenti

Guide Xlogic correlate

• Errore 413 Content Too Large: upload e proxy
• Errore 409 Conflict: API, salvataggi e risorse
• Limiti PHP: upload_max_filesize, post_max_size e timeout

Fonti tecniche

• MDN: 415 Unsupported Media Type