Cerca articoli della Knowledge Base

HTTP 413 Payload Too Large: limite upload

Cos'e HTTP 413 Payload Too Large

Il codice HTTP 413 Payload Too Large (in passato noto come "Request Entity Too Large") indica che il body della richiesta supera la dimensione massima accettata dal server o da uno dei livelli intermedi. E uno degli errori più frequenti nelle applicazioni che gestiscono upload di file.

Cause comuni

  • Upload di immagini, video o documenti oltre il limite configurato.
  • API che ricevono JSON troppo grandi (es. import di massa).
  • Cookie session eccessivamente gonfi.
  • Form multipart con molti campi e file.

Configurazione Nginx

La direttiva principale e client_max_body_size:

server {
    listen 443 ssl;
    server_name esempio.gtechgroup.it;

    client_max_body_size 100M;  # consente fino a 100MB

    location /api/upload {
        client_max_body_size 500M;  # override per endpoint specifico
        proxy_pass http://backend;
    }
}

Default Nginx: 1MB. Se non configurato esplicitamente, qualsiasi upload superiore a 1MB fallisce.

Configurazione Apache

Per Apache si usa LimitRequestBody:

<Directory /var/www/upload>
    LimitRequestBody 104857600  # 100MB in bytes
</Directory>

Default: 0 (illimitato), ma PHP e altri moduli applicano i propri limiti.

Configurazione PHP

PHP ha tre direttive in php.ini che possono generare 413:

upload_max_filesize = 100M
post_max_size = 110M
memory_limit = 256M

Regola d'oro: post_max_size >= upload_max_filesize, e memory_limit >= post_max_size. Altrimenti ottieni errori incoerenti.

Configurazione Node.js Express

const express = require('express');
const app = express();

app.use(express.json({ limit: '50mb' }));
app.use(express.urlencoded({ limit: '50mb', extended: true }));

Default Express: 100KB per JSON. Va sempre alzato per API che accettano payload grandi.

Cloudflare e CDN limits

I CDN hanno propri limiti che si sommano:

  • Cloudflare Free: 100MB max upload.
  • Cloudflare Pro: 100MB.
  • Cloudflare Business: 200MB.
  • Cloudflare Enterprise: 500MB+ configurabile.

Per upload oltre questi limiti, usa upload diretto verso S3/Google Cloud Storage con presigned URL, bypassando il CDN.

Diagnosticare l'origine del 413

Quando si verifica un 413, controlla la catena dall'esterno verso l'interno:

  1. CDN (Cloudflare/CloudFront).
  2. Load balancer (AWS ALB, HAProxy).
  3. Reverse proxy (Nginx, Apache).
  4. Application server (PHP-FPM, Node, Gunicorn).
  5. Framework limits.

Test con curl e file di dimensione nota: curl -X POST -F "file=@bigfile.bin" https://example.com/upload. Esamina l'header Server: nella risposta per capire chi ha emesso il 413.

Risposta del server

Il server dovrebbe includere un body informativo:

HTTP/1.1 413 Payload Too Large
Content-Type: application/json
Connection: close

{
  "error": "File exceeds maximum size of 100MB",
  "max_size_bytes": 104857600
}

Nota: il server puo chiudere la connessione (Connection: close) per evitare di leggere body enormi.

Strategie per upload grandi

  • Chunked upload: spezza file in chunk da 5-10MB inviati separatamente, riassemblati lato server.
  • Resumable upload: protocolli come tus.io permettono di riprendere upload interrotti.
  • Direct-to-S3: client uploada direttamente al bucket con presigned URL, server riceve solo metadata.
  • WebSocket streaming: per scenari particolari, bypassa HTTP request size limits.

Validazione lato client

Per migliorare UX, controlla la dimensione del file prima di inviarlo:

const MAX_SIZE = 100 * 1024 * 1024; // 100MB
fileInput.addEventListener('change', e => {
    if (e.target.files[0].size > MAX_SIZE) {
        alert('File troppo grande (max 100MB)');
        e.target.value = '';
    }
});

Header Retry-After

Il 413 puo includere Retry-After se il limite e temporaneo (es. durante manutenzione). Tuttavia, di solito il 413 e definitivo: il client deve ridurre il payload o usare un'endpoint diverso.

Chunked upload per file grandi

Per file oltre i limiti standard, l'approccio più robusto e dividere in chunk e uploadare separatamente. Algoritmo: client divide il file in pezzi da 5-10MB, calcola hash di ogni chunk, fa POST /upload/chunk con metadata. Server riassembla quando tutti i chunk sono arrivati. Permette retry per singolo chunk, progress bar accurate, resume da interruzioni.

Tus.io protocol

Tus.io e uno standard open-source per resumable uploads. Definisce header come Upload-Length, Upload-Offset, Tus-Resumable. Implementato da molti SDK e da servizi cloud (Vimeo per upload video). Risolve elegantemente il problema di 413 e instabilita di rete.

Presigned URL per direct-to-S3

Per upload massivi, bypassa completamente il tuo server: il backend genera un'URL S3 presigned che il client usa per uploadare direttamente. Vantaggi: nessun limite 413 sul tuo Nginx, nessun consumo CPU/RAM del tuo server, scalabilità illimitata. Pattern standard per app moderne con upload utente.

Cliente HTML5 con progress

const xhr = new XMLHttpRequest();
xhr.upload.addEventListener('progress', e => {
    if (e.lengthComputable) {
        const pct = (e.loaded / e.total) * 100;
        progressBar.style.width = pct + '%';
    }
});
xhr.open('POST', '/upload');
xhr.send(formData);

Sicurezza e validazione

Limiti generosi di upload aprono superficie attacco: validazione tipo file (magic bytes, non solo extension), antivirus scan post-upload, isolation in directory non eseguibili, rename con UUID per evitare path traversal. Mai fidarsi del filename inviato dal client.

Configurazione PHP-FPM

Oltre a php.ini, considerare anche pool config (es. www.conf): request_terminate_timeout per upload molto lunghi, php_admin_value[upload_max_filesize] per override per-pool. Su shared hosting, limiti spesso sono settati dall'admin Plesk e non modificabili.

S3 multipart upload

AWS S3 multipart upload e la soluzione enterprise: file e splittato in parti da min 5MB, ogni parte uploadata in parallelo, alla fine S3 le ricombina. SDK ufficiali (boto3, AWS SDK JS) lo gestiscono trasparentemente. Limite: 5TB per file, 10000 parti per upload.

413 e CDN purge

Quando ricevi 413 in cascata di CDN, ricorda che il limite più restrittivo prevale. Aumentando il limite Nginx senza aumentare quello Cloudflare resta inutile. Diagnostica end-to-end con curl direttamente su origin (bypassando CDN).

Hai bisogno di aiuto?

Se il tuo sito mostra errori HTTP, il team di G Tech Group puo aiutarti. Contattaci tramite il modulo di contatto.

Hai trovato utile quest'articolo?

Articoli Correlati