413 Request Entity Too Large
Cererea are un corp mai mare decât acceptă serverul sau proxy-ul din față (la nginx, implicit 1 MB prin `client_max_body_size`). Pentru fișiere mari, soluția bună nu e să mărești limita, ci să lași clientul să încarce direct în object storage, cu un URL presemnat.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Codul 413 (în specificațiile noi numit 413 Content Too Large) înseamnă că serverul refuză cererea din cauza mărimii corpului, înainte să o proceseze. Primul care refuză e de obicei nginx, cu limita client_max_body_size de 1 MB; apoi pot refuza load balancer-ul, API gateway-ul sau framework-ul (Spring are spring.servlet.multipart.max-file-size, Express are limita din express.json({ limit })).
Limita există cu motiv: fiecare upload ține ocupată o conexiune, memorie și un worker al serverului cât timp se transferă fișierul. Dacă mărești doar limita, serverele de aplicație ajung să care gigaocteți de video și obosesc la câteva upload-uri simultane.
În system design, upload-urile mari ocolesc serverele: aplicația generează un URL presemnat (S3, GCS, Azure Blob), clientul încarcă direct acolo, iar serverul primește doar metadatele și un eveniment când fișierul a ajuns.
De ce apare: cauzele frecvente
1Fișierele trec prin serverul de aplicație
POST /api/videoclipuri (corp: fișierul de 500 MB)
-> nginx: 413 Request Entity Too LargePOST /api/videoclipuri/url-upload -> { url presemnat, valabil 15 min }
PUT <url presemnat> (fișierul, direct în object storage)
POST /api/videoclipuri/{id}/gataServerul nu mai transportă fișierul, doar emite permisiunea. Object storage-ul e făcut pentru transferuri mari și scalează singur.
2Limita nginx lăsată implicit pentru un formular cu poze
server {
location /api/ { proxy_pass http://app; }
}server {
location /api/poze { client_max_body_size 10m; proxy_pass http://app; }
}Pentru fișiere mici (o poză de profil) poți ridica limita doar pe ruta respectivă, nu global.
Repară eroarea, direct în pagină
Utilizatorii încarcă videoclipuri de câte 20 MB, iar toate trec prin serverele de aplicație (care răspund des cu 413 și sunt ocupate cu transferul). Fă ca fișierele să ajungă direct în object storage, fără să mai treacă prin servere.
Indiciu
Clientul poate vorbi direct cu object storage-ul, dacă primește un URL presemnat.
Reparația
1. Conectează Client web → Object storage (upload direct, cu URL presemnat de la server).
Rezultat: serverul nu mai transferă fișierele, iar avertismentul despre upload prin server dispare.
De ce merge
Cu conexiunea Client → Object storage, upload-urile merg direct acolo, cu URL presemnat. Serverele nu mai poartă fișierele: avertismentul upload-app dispare, iar încărcarea lor scade.
Alte forme ale mesajului
413 Content Too Largeclient intended to send too large body: 5242880 bytes (logul nginx)MaxUploadSizeExceededException: Maximum upload size exceededPayloadTooLargeError: request entity too large
Cum o eviți pe viitor
- Pentru fișiere mai mari de câțiva MB folosește URL-uri presemnate și upload direct în object storage.
- Ridică limita doar pe rutele care chiar primesc fișiere, nu global.
- Validează pe client mărimea înainte de upload și arată un mesaj clar.
- Procesează fișierul (redimensionare, transcodare) asincron, după upload.
Întrebări frecvente
Am mărit client_max_body_size, dar tot primesc 413. De ce?
Limita poate fi și în altă componentă: load balancer-ul, API gateway-ul (API Gateway din AWS are o limită fixă de 10 MB) sau framework-ul aplicației. Verifică fiecare strat de pe drum.
Cum știe serverul că fișierul a ajuns în object storage?
Fie clientul anunță explicit după upload, fie object storage-ul trimite un eveniment (de exemplu o notificare S3 spre o coadă), pe care îl preia un worker.
Erori înrudite
upstream prematurely closed connection while reading response header from upstream Serverul din spatele nginx a închis conexiunea înainte să trimită răspunsul, deci clientul primește 502. Cel mai des procesul a căzut (excepție netratată, OOM kill) sau a închis o conexiune keep-alive pe care nginx tocmai o refolosea. Caută în logurile aplicației și în `dmesg` exact la momentul erorii. Imaginile și fișierele CSS/JS se încarcă greu: sunt servite de serverul de aplicație, fără CDN Fiecare imagine, fișier CSS sau JS trece prin load balancer și prin serverul de aplicație, de la un singur centru de date, deci se încarcă lent pentru utilizatorii îndepărtați și ocupă serverele. Pune un CDN în fața lor: fișierele se servesc din noduri apropiate de utilizator, iar serverul vede doar ratările. could not extend file "base/16384/24576": No space left on device (fișiere salvate pe disc / în bază) Discul bazei de date (sau al serverului) s-a umplut, de obicei pentru că fișierele încărcate de utilizatori (poze, PDF-uri) sunt salvate în bază sau pe discul local. Mută fișierele într-un object storage și păstrează în bază doar metadatele (cheia fișierului, mărimea, proprietarul). Învață System Design de la zero, cu exerciții la fiecare lecție
Curs System Design: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 10 lecții sunt gratuite.
