Como corrigir erro muito grande da entidade de solicitação 413 em Nginx e Node.js

O erro413 Entidade de solicitação muito grande significa que o corpo da solicitação (geralmente um upload de arquivo ou uma grande carga JSON) excede o limite de tamanho permitido pelo seu servidor. Muitas vezes aparece apenas na produção por causa dos padrões do nginx. Veja como consertar isso em todas as camadas.

O que causa esse erro

Várias camadas podem rejeitar uma solicitação grande:

• Nginx (proxy reverso) tem um limite de corpo padrão de 1 MB
• Expresso/Node.js o analisador de corpo tem seu próprio limite (padrão ~ 100 KB)
• Carregar middleware (multer) tem limites de tamanho de arquivo configuráveis A solicitação deve passar por TODAS as camadas – corrigir apenas uma pode não resolver o problema.

Correção 1: Nginx client_max_body_size

Correção 2: Limite do analisador de corpo expresso

# nginx is the most common culprit — default is 1MB

# In your server or location block:
server {
    # Allow up to 50MB request bodies
    client_max_body_size 50M;

    location /api/upload {
        client_max_body_size 100M;   # larger for upload endpoints
        proxy_pass http://localhost:3000;
    }
}

# Or globally in http block (/etc/nginx/nginx.conf):
http {
    client_max_body_size 50M;
}

# Reload nginx after changing
sudo nginx -t && sudo systemctl reload nginx

Correção 3: Limites de upload de arquivos Multer

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

// 🐛 Default limit is ~100KB — large JSON fails
app.use(express.json());

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

// For specific routes only:
app.post('/api/large', express.json({ limit: '100mb' }), handler);

Todas as três camadas juntas

const multer = require('multer');

// Configure size limits for file uploads
const upload = multer({
  storage: multer.diskStorage({ /* ... */ }),
  limits: {
    fileSize: 50 * 1024 * 1024,   // 50MB per file
    files: 5,                      // max 5 files
  },
});

app.post('/upload', upload.single('file'), (req, res) => {
  res.json({ filename: req.file.filename });
});

// Handle multer's own limit error gracefully
app.use((err, req, res, next) => {
  if (err instanceof multer.MulterError && err.code === 'LIMIT_FILE_SIZE') {
    return res.status(413).json({ error: 'File too large (max 50MB)' });
  }
  next(err);
});

Para que um upload de 50 MB seja bem-sucedido, todos os limites devem permitir isso:

Correção para outros servidores

# 1. nginx (if used as reverse proxy)
client_max_body_size 50M;

# 2. Express body parser (for JSON/form data)
app.use(express.json({ limit: '50mb' }));

# 3. Multer (for multipart file uploads)
limits: { fileSize: 50 * 1024 * 1024 }

# The SMALLEST limit wins — the request fails at the first layer that rejects it

Melhor abordagem: fazer upload diretamente para o armazenamento de objetos

# Apache — in .htaccess or config
LimitRequestBody 52428800   # 50MB in bytes

# Cloudflare — free plan limits uploads to 100MB
# (upgrade or upload directly to storage for larger files)

# Next.js API routes — configure the body size limit
export const config = {
  api: {
    bodyParser: { sizeLimit: '50mb' },
  },
};

Para arquivos grandes, não os encaminhe através do servidor do seu aplicativo — use URLs pré-assinados para fazer upload diretamente para o S3/armazenamento em nuvem:

Perguntas Frequentes

// Backend generates a presigned upload URL
app.post('/api/presign', async (req, res) => {
  const url = await s3.getSignedUrl('putObject', {
    Bucket: 'my-bucket',
    Key: `uploads/${req.body.filename}`,
    Expires: 300,
  });
  res.json({ uploadUrl: url });
});

// Frontend uploads directly to S3 — bypasses your server's limits entirely
const { uploadUrl } = await fetch('/api/presign', { /* ... */ }).then(r => r.json());
await fetch(uploadUrl, { method: 'PUT', body: file });
// No 413 — the file never passes through your app server

P: Por que funciona localmente, mas falha na produção?

R: A produção geralmente tem nginx (ou outro proxy reverso) na frente do seu aplicativo com um limite de corpo padrão de 1 MB. Localmente, você acessa seu aplicativo diretamente, sem esse proxy. Aumentar
em nginx.client_max_body_sizeP: Aumentei o limite do Express, mas ainda recebo 413. Por quê?

R: O nginx está rejeitando a solicitação antes que ela chegue ao Express. O proxy reverso
também deve ser aumentado. Corrija todas as camadas – o menor limite vence.client_max_body_sizeP: Qual é um limite razoável de tamanho corporal?

R: Defina-o tão baixo quanto seu caso de uso permitir – limites grandes aumentam o risco de abuso/DoS. Para APIs JSON, alguns MB são suficientes. Para uploads de arquivos, dimensione para o maior arquivo legítimo ou, melhor, faça upload diretamente para o armazenamento de objetos.
P: Os arquivos grandes devem passar pelo meu servidor de aplicativos?

R: Idealmente não – use URLs pré-assinados para fazer upload diretamente para S3/armazenamento em nuvem. Isso evita totalmente os limites de tamanho do corpo, reduz a carga do servidor e é melhor dimensionado. Roteie apenas metadados por meio do seu aplicativo.
P: Como retorno um erro amigável em vez de um 413 bruto?

R: Capture o erro de limite em seu middleware (LIMIT_FILE_SIZE do multer ou um erro do analisador de corpo) e retorne uma mensagem JSON clara. Valide também o tamanho do arquivo no frontend antes de carregá-lo para fornecer feedback imediato.
Conclusão

“413 Request Entity Too Large” significa que o corpo da solicitação excede o limite do servidor – e geralmente possui várias camadas. A correção:

aumentar no nginx, aumente o analisador de corpo do Expressclient_max_body_sizee configure o multerlimit — todos os três devem permitir o tamanho, já que o menor limite vence. Normalmente aparece em produção devido ao padrão de 1 MB do nginx. Para arquivos grandes, a melhor solução é fazer upload diretamente para o armazenamento de objetos com URLs pré-assinados, ignorando totalmente os limites do servidor de aplicativos e dimensionando melhor.fileSize — todos os três devem permitir o tamanho, já que o menor limite vence. Normalmente aparece em produção devido ao padrão de 1 MB do nginx. Para arquivos grandes, a melhor solução é fazer upload diretamente para o armazenamento de objetos com URLs pré-assinados, ignorando totalmente os limites do servidor de aplicativos e dimensionando melhor.