...
Eroare System Design · CDN, fișiere statice și upload-uri

413 Request Entity Too Large

Pe scurt

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

Greșit
POST /api/videoclipuri   (corp: fișierul de 500 MB)
  -> nginx: 413 Request Entity Too Large
Corect
POST /api/videoclipuri/url-upload  -> { url presemnat, valabil 15 min }
PUT  <url presemnat>  (fișierul, direct în object storage)
POST /api/videoclipuri/{id}/gata

Serverul 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

Greșit
server {
    location /api/ { proxy_pass http://app; }
}
Corect
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ă tu

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.

Alte forme ale mesajului

  • 413 Content Too Large
  • client intended to send too large body: 5242880 bytes (logul nginx)
  • MaxUploadSizeExceededException: Maximum upload size exceeded
  • PayloadTooLargeError: 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

← Toate erorile System Design

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Î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.