Códigos de Estado HTTP: Referencia Completa

Códigos de Estado HTTP: Lo Que Tu Servidor Realmente Le Dice al Cliente

Toda respuesta HTTP incluye un código de estado de tres dígitos. Acertalos y tu API es intuitiva. Errarlos y los desarrolladores pasan horas depurando por qué el cliente hace retry en un 200 que debería ser 400.

Las Cinco Clases

Códigos de Éxito (2xx)

// Ejemplos Express.js
app.post('/users', (req, res) => {
  const user = createUser(req.body);
  res.status(201).json(user);
});

app.delete('/users/:id', (req, res) => {
  deleteUser(req.params.id);
  res.status(204).send();
});

app.post('/reports', (req, res) => {
  queueReportGeneration(req.body);
  res.status(202).json({ message: 'Reporte siendo generado' });
});

Códigos de Redirección (3xx)

Error común: Usar 302 cuando debería ser 301. Si el cambio de URL es permanente (mudó a nuevo dominio, cambió estructura de URL), usa 301 para que los buscadores actualicen su índice.

Códigos de Error del Cliente (4xx)

// 400 vs 422 — ambos son válidos, elige una convención
// 400: solicitud es estructuralmente incorrecta (JSON malformado)
// 422: solicitud es estructuralmente correcta, pero datos son inválidos

app.post('/users', (req, res) => {
  if (!req.body.email) {
    return res.status(422).json({
      error: 'Validación falló',
      details: [{ field: 'email', message: 'Email es requerido' }]
    });
  }
});

Códigos de Error del Servidor (5xx)

Principio clave: 4xx significa que el cliente necesita corregir algo. 5xx significa que el servidor necesita corregir algo. Si el cliente nunca puede tener éxito cambiando su solicitud, es un 5xx.

Árbol de Decisión

¿La solicitud es válida?
├── No → ¿Es un problema estructural?
│   ├── Sí → 400 Bad Request
│   └── No → 422 Unprocessable Entity
├── Sí → ¿El usuario está autenticado?
│   ├── No → 401 Unauthorized
│   └── Sí → ¿El usuario está autorizado?
│       ├── No → 403 Forbidden
│       └── Sí → ¿El recurso existe?
│           ├── No → 404 Not Found
│           └── Sí → ¿Se procesó con éxito?
│               ├── Sí → 200/201/204
│               └── No → 500 Internal Server Error

Referencia rápida: Códigos de Estado HTTP — tabla buscable con descripciones, categorías y ejemplos para cada código.