Códigos de estado HTTP (200, 201, 400, 404, 500, etc.)

1 ¿Qué son los códigos de estado HTTP?

Cada vez que hacemos una petición a una API REST, el servidor responde con:

  • Un cuerpo (body): datos en JSON, XML, texto, etc.
  • Un encabezado (headers): metadatos de la respuesta.
  • Un código de estado (status code): número de 3 dígitos que indica el resultado de la operación.

👉 Ejemplo real de respuesta:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "nombre": "Notebook",
  "precio": 1500
}

El 200 OK nos dice que la petición fue exitosa.

2 Clasificación de los códigos HTTP

Los códigos están divididos en 5 categorías según el primer dígito:

  • 1xx (100–199): respuestas informativas.
  • 2xx (200–299): peticiones exitosas.
  • 3xx (300–399): redirecciones.
  • 4xx (400–499): errores del cliente.
  • 5xx (500–599): errores del servidor.

3 Códigos más usados en APIs REST

A) Respuestas exitosas (2xx)

200 OK
La petición fue procesada correctamente. Se usa en GET, PUT, PATCH, DELETE.

GET /usuarios/1  →  200 OK

201 Created
Indica que un nuevo recurso fue creado correctamente. Generalmente usado en POST.

POST /productos  →  201 Created

202 Accepted
La petición fue aceptada, pero el procesamiento aún no terminó. Se usa en procesos asíncronos.

204 No Content
La operación fue exitosa, pero no hay nada que devolver.

DELETE /usuarios/1  →  204 No Content

B) Errores del cliente (4xx)

400 Bad Request
La petición está mal formada o faltan datos. Ejemplo: enviar JSON inválido o un campo obligatorio ausente.

401 Unauthorized
El cliente no está autenticado. Falta el header Authorization. Más info: MDN 401.

403 Forbidden
El cliente está autenticado, pero no tiene permisos para acceder al recurso.

404 Not Found
El recurso no existe. Ejemplo: GET /productos/999 cuando ese producto no está en la base.

405 Method Not Allowed
El método HTTP usado no está permitido en esa ruta. Ejemplo: DELETE /usuarios en una API que no soporta borrado.

409 Conflict
Conflicto en la petición, por ejemplo, intentar crear un usuario con un email ya existente.

429 Too Many Requests
El cliente hizo demasiadas peticiones en poco tiempo (limitación por seguridad).

C) Errores del servidor (5xx)

500 Internal Server Error
Error genérico del servidor. Indica que algo falló del lado del backend.

502 Bad Gateway
El servidor recibió una respuesta inválida de otro servicio al que consultó.

503 Service Unavailable
El servidor está temporalmente fuera de servicio (mantenimiento o sobrecarga).

504 Gateway Timeout
El servidor no recibió respuesta a tiempo de otro servicio.

4 Ejemplos prácticos en APIs REST

Ejemplo 1 — Crear un recurso

POST /usuarios
Body: { "nombre": "Ana", "email": "ana@ejemplo.com" }

Respuesta:
201 Created
{
  "id": 5,
  "nombre": "Ana",
  "email": "ana@ejemplo.com"
}

Ejemplo 2 — Recurso no encontrado

GET /usuarios/99

Respuesta:
404 Not Found
{
  "error": "Usuario no existe"
}

Ejemplo 3 — Error del cliente (JSON mal formado)

POST /productos
Body: { "nombre": "Tablet", "precio": 1200, }   <-- coma extra

Respuesta:
400 Bad Request
{
  "error": "JSON inválido"
}

Ejemplo 4 — Sin autenticación

GET /pedidos

Respuesta:
401 Unauthorized
{
  "error": "Se requiere token de autorización"
}

Ejemplo 5 — Eliminación exitosa sin datos

DELETE /productos/10

Respuesta:
204 No Content

5 Buenas prácticas con códigos de estado

  • Usar siempre el código correcto para que el cliente entienda qué pasó. No devolver 200 OK cuando hubo un error.
  • Acompañar el código con un mensaje claro en JSON.

Ejemplo

{ "error": "El campo 'email' es obligatorio" }
  • Usar 201 Created cuando se crea un recurso nuevo.
  • Usar 204 No Content en DELETE para evitar devolver datos innecesarios.
  • Evitar mensajes genéricos con 500 Internal Server Error: siempre que sea posible, dar más detalle (sin exponer información sensible).

6 Conclusión del capítulo

Los códigos de estado HTTP son fundamentales para la comunicación entre cliente y servidor en una API REST:

  • 2xx: éxito (200 OK, 201 Created, 204 No Content).
  • 4xx: error del cliente (400 Bad Request, 401 Unauthorized, 404 Not Found).
  • 5xx: error del servidor (500 Internal Server Error, 503 Service Unavailable).

👉 Usar correctamente los códigos hace que una API sea clara, profesional y fácil de consumir.

Retornar