Códigos de estado HTTP: Guía de referencia completa para desarrolladores

Los códigos de estado HTTP son números de tres dígitos devueltos por un servidor. Esta referencia completa de códigos HTTP cubre todos los códigos que encontrarás en la práctica.

Consulta cualquier código HTTP con nuestra herramienta →

1xx — Informativo

El servidor recibió la solicitud y sigue procesándola.

2xx — Éxito

La categoría más común. La solicitud fue procesada exitosamente.

3xx — Redirección

El cliente necesita realizar una acción adicional.

4xx — Errores del cliente

El problema está del lado del cliente.

5xx — Errores del servidor

El servidor no pudo completar la solicitud.

Mejores prácticas para códigos API

El código correcto hace tu API más intuitiva.

// REST API Status Code Guidelines

// Creating a resource
POST /api/users → 201 Created (with Location header)

// Successful read
GET /api/users/123 → 200 OK

// Successful update
PUT /api/users/123 → 200 OK (with updated resource)
PATCH /api/users/123 → 200 OK

// Successful delete
DELETE /api/users/123 → 204 No Content

// Validation error
POST /api/users (invalid data) → 422 Unprocessable Entity
{
  "error": "Validation failed",
  "details": [
    { "field": "email", "message": "Invalid email format" }
  ]
}

// Authentication required
GET /api/admin → 401 Unauthorized
{ "error": "Authentication required" }

// No permission
GET /api/admin (as regular user) → 403 Forbidden
{ "error": "Insufficient permissions" }

// Resource not found
GET /api/users/999 → 404 Not Found
{ "error": "User not found" }

// Rate limit exceeded
GET /api/search → 429 Too Many Requests
Retry-After: 60
{ "error": "Rate limit exceeded", "retry_after": 60 }

Escenarios comunes de depuración

Los códigos HTTP son tu primera pista al depurar.

CORS Errors (Browser shows "blocked by CORS")

The browser blocks the request, but the actual HTTP status may be hidden. Check server logs. Ensure your server sends the correct Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers headers.

502 Bad Gateway on Deployment

Your reverse proxy (Nginx, Cloudflare) can't reach your application server. Check: Is the app process running? Is it listening on the correct port? Are there firewall rules blocking the connection?

# Check if your app is running
ps aux | grep node

# Check if it's listening on the expected port
netstat -tlnp | grep 3000

# Check Nginx error logs
tail -f /var/log/nginx/error.log

504 Gateway Timeout

The upstream server is too slow. Common causes: slow database queries, external API timeouts, or large file processing. Solutions: optimize queries, add timeouts to external calls, use background jobs for heavy tasks.

429 Rate Limiting

// Implementing exponential backoff in JavaScript
async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url);
    if (response.status !== 429) return response;

    const retryAfter = response.headers.get('Retry-After');
    const delay = retryAfter
      ? parseInt(retryAfter) * 1000
      : Math.pow(2, i) * 1000; // 1s, 2s, 4s

    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error('Max retries exceeded');
}

Preguntas frecuentes

¿Diferencia entre 401 y 403?

401 = falta autenticación. 403 = autenticado pero sin permisos.

¿Cuándo usar 200 vs 201?

200 para solicitudes exitosas, 201 al crear un nuevo recurso.

¿Qué significa 418?

Una broma del 1 de abril de 1998. El servidor es una tetera.

¿301 vs 302 para SEO?

301 = permanente (transfiere SEO). 302 = temporal.

¿Cómo manejar 429?

Revisar Retry-After e implementar backoff exponencial.

Entender los códigos HTTP es fundamental. Usa nuestra herramienta.

Consulta códigos con nuestra herramienta HTTP →