¿Qué es multipart/form-data Content-Type? Uploads, Ejemplos

¿Qué es multipart/form-data?

multipart/form-data es un Content-Type de request HTTP usado para enviar datos de form que contienen archivos o contenido binario junto con campos de texto. A diferencia de application/x-www-form-urlencoded (la encoding default de form para campos solo texto), multipart/form-data envía cada campo de form como una "parte" separada en el body del request, con sus propios headers y contenido. Esta estructura es esencial para uploads de archivos — los bytes binarios del archivo no pueden ser URL-encoded como key=value de forma segura.

El formato está definido en RFC 7578. Los browsers automáticamente lo usan cuando un form HTML tiene enctype="multipart/form-data" y contiene un elemento <input type="file">.

Cómo funciona multipart/form-data

El header Content-Type incluye un boundary — un string generado aleatoriamente que separa cada parte en el body del request:

POST /api/upload HTTP/1.1
Host: api.example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Length: 554

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="username"

alice
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="avatar"; filename="photo.jpg"
Content-Type: image/jpeg

[bytes binarios JPEG aquí]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Cada parte está precedida por -- + el string boundary. Cada parte tiene su propio header Content-Disposition y Content-Type opcional.

multipart/form-data vs application/x-www-form-urlencoded

Cuándo usar multipart/form-data

• Uploads de archivos. El use case original.
• Forms texto + archivo mixtos.
• Múltiples archivos en un request.
• Submission de form con texto no-ASCII.

Enviando multipart/form-data desde código

JavaScript (browser fetch + FormData)

const fd = new FormData();
fd.append('username', 'alice');
fd.append('avatar', fileInput.files[0]);

fetch('/api/upload', {
  method: 'POST',
  body: fd  // Browser setea Content-Type con boundary automáticamente
});

Importante: NO seteas Content-Type manualmente al enviar FormData — el browser necesita agregar el boundary él mismo.

curl

curl -X POST https://api.example.com/upload \
  -F "username=alice" \
  -F "avatar=@/path/to/photo.jpg"

Python (requests)

import requests
files = {'avatar': open('photo.jpg', 'rb')}
data = {'username': 'alice'}
requests.post('https://api.example.com/upload', files=files, data=data)

Parsing server-side

• Express + Multer.
• Django. request.FILES['avatar']
• Flask. request.files['avatar']
• FastAPI. def upload(file: UploadFile)
• Spring Boot. @RequestParam MultipartFile
• Rails. params[:avatar]

Límites de upload multipart y gotchas

• Límites de body size del server. NGINX default 1 MB; AWS API Gateway 10 MB; Cloudflare 100 MB Pro.
• Presión de memoria en uploads. Usa parsers streaming.
• Colisiones de boundary. Teóricamente posibles, extremadamente raras.
• CSRF en uploads. Endpoints de upload necesitan la misma protección CSRF que otros endpoints state-changing.
• Validación de file-type. No confíes en el Content-Type del cliente. Valida basado en contenido real del archivo (magic bytes).

Consideraciones de performance

• Evita enviar archivos grandes a través de tu API server. Usa URLs signed S3/Cloud Storage para upload directo.
• Uploads chunked / resumable. Para archivos muy grandes protocolos como tus.io o AWS S3 multipart upload.
• HTTP/2. Ayuda con uploads multi-archivo.

Errores comunes

• 413 Payload Too Large.
• 400 Bad Request — boundary faltante.
• 500 — excepción del parser multipart.
• Archivo vacío recibido. Cliente usó FormData pero seteó Content-Type manualmente.

Testing uploads multipart at scale

• Varía tamaños de archivo.
• Usa contenido real de archivo.
• Testea casos boundary.
• Multi-región.
• Uploads concurrentes.

FAQ: multipart/form-data

¿Por qué está el boundary en el header Content-Type?

El server necesita saber el boundary para parsear el body. No puede derivarlo del body mismo.

¿Puedo usar multipart/form-data sin archivos?

Sí. Funciona para campos solo texto también. Pero para forms solo texto, application/x-www-form-urlencoded o JSON es más eficiente.

¿Cuál es la diferencia entre multipart/form-data y multipart/mixed?

Ambos son multipart, pero multipart/form-data es específico para submissions de form HTML. multipart/mixed es más genérico.

¿Cómo envío JSON + un archivo juntos?

Dos patterns: (1) una parte es text/JSON, otra es el archivo; (2) embebir el archivo como base64 dentro de JSON (~33% overhead).

¿Por qué falla mi upload cuando seteo Content-Type manualmente?

Porque no incluiste el boundary. Deja que tu cliente HTTP setee el header automáticamente.

¿Cuál es el tamaño máximo de archivo para uploads multipart?

Depende del config del server. NGINX default 1 MB. AWS API Gateway hard cap 10 MB. Para archivos más grandes URLs S3 signed o uploads chunked (tus.io).

Testea endpoints de upload multipart con LoadFocus

Si estás load-testeando APIs de upload de archivos, LoadFocus corre scripts JMeter y k6 que pueden enviar payloads multipart realistas desde 25+ regiones cloud con hasta 12.500 VUs. Regístrate en loadfocus.com/signup — sin tarjeta de crédito — y corre tu primer test multipart upload en menos de 5 minutos.