Blog

¿Qué Códigos de Estado HTTP Deberían Usar Realmente las APIs REST?

Ashley Innocent

Ashley Innocent

13 March 2026

¿Qué Códigos de Estado HTTP Deberían Usar Realmente las APIs REST?

Apidog para empresas

Despliegue local

SSO & RBAC

Conforme con SOC 2

Explorar Apidog Enterprise

Resumen

Las API REST deben usar los códigos de estado HTTP correctamente: 200 para GET exitosos, 201 para POST exitosos con creación de recursos, 204 para DELETE exitosos, 400 para errores del cliente, 401 para fallos de autenticación, 404 para no encontrado y 500 para errores del servidor. Modern PetstoreAPI implementa todos los códigos de estado HTTP estándar con la semántica adecuada y respuestas de error RFC 9457.

Introducción

Tu API devuelve 200 OK para todo. ¿Éxito? 200 OK. ¿Error de validación? 200 OK con un mensaje de error en el cuerpo. ¿Recurso no encontrado? 200 OK con {"error": "not found"}. ¿Fallo de autenticación? Lo adivinaste: 200 OK.

Esto es incorrecto. Los códigos de estado HTTP existen por una razón. Le indican a los clientes lo que sucedió sin necesidad de analizar el cuerpo de la respuesta. Las cachés, los proxies y las herramientas de monitoreo dependen de los códigos de estado. Cuando devuelves 200 para errores, rompes todo el ecosistema HTTP.

El antiguo Swagger Petstore cometía errores en los códigos de estado: devolvía 200 para las solicitudes POST que deberían devolver 201, usaba 200 para las operaciones DELETE que deberían devolver 204 y carecía de códigos de error importantes. Modern PetstoreAPI soluciona esto implementando la semántica HTTP adecuada en todos los endpoints.

💡
Si estás construyendo o probando API REST, Apidog te ayuda a validar el uso de códigos de estado, probar escenarios de error y asegurar que tu API sigue los estándares HTTP. Puedes definir códigos de estado esperados, ejecutar pruebas automatizadas y detectar respuestas incorrectas antes del despliegue.
botón

En esta guía, aprenderás qué códigos de estado HTTP son importantes para las API REST, cuándo usar cada uno y cómo Modern PetstoreAPI los implementa correctamente.

El Problema de los Códigos de Estado

Muchas API tratan los códigos de estado como una ocurrencia tardía. El resultado: semántica HTTP rota y clientes confundidos.

El Anti-Patrón "200 OK para Todo"

// Éxito
GET /users/123
200 OK
{"id": 123, "name": "John"}

// Error (¡pero aún 200!)
GET /users/999
200 OK
{"error": "User not found"}

// Error de validación (¡aún 200!)
POST /users
200 OK
{"error": "Email is required"}

Problemas:

Por Qué Sucede Esto

Los desarrolladores devuelven 200 porque:

  1. No conocen los otros códigos de estado
  2. Creen que los códigos de estado son opcionales
  3. Quieren evitar "romper" a los clientes
  4. Están copiando malos ejemplos (como el antiguo Swagger Petstore)

Códigos de Estado HTTP Esenciales para API REST

No necesitas los más de 60 códigos de estado HTTP. Concéntrate en estos esenciales.

Referencia Rápida

Éxito (2xx):

Errores del Cliente (4xx):

Errores del Servidor (5xx):

Códigos de Éxito (2xx)

Los códigos de éxito indican que la solicitud fue exitosa. Diferentes códigos transmiten diferentes significados.

200 OK

Usar para: Solicitudes GET, PUT, PATCH exitosas que devuelven datos.

GET /pets/123
200 OK
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

No usar para: Solicitudes POST que crean recursos (usar 201), solicitudes DELETE (usar 204).

201 Created

Usar para: Solicitudes POST exitosas que crean un nuevo recurso.

POST /pets
201 Created
Location: https://petstoreapi.com/pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

Puntos clave:

Modern PetstoreAPI devuelve 201 para todas las operaciones POST que crean recursos.

204 No Content

Usar para: Solicitudes DELETE, PUT o PATCH exitosas sin cuerpo de respuesta.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
204 No Content

Puntos clave:

Códigos de Error del Cliente (4xx)

Los códigos de error del cliente indican que el cliente cometió un error. La solicitud no debe reintentarse sin modificación.

400 Bad Request

Usar para: Solicitudes mal formadas, JSON inválido, campos requeridos faltantes.

POST /pets
400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Error de Validación",
  "status": 400,
  "detail": "La validación de la solicitud falló",
  "invalid-params": [
    {
      "name": "name",
      "reason": "El nombre es obligatorio"
    }
  ]
}

Modern PetstoreAPI utiliza el formato RFC 9457 para todas las respuestas de error.

401 Unauthorized

Usar para: Credenciales de autenticación faltantes o inválidas.

GET /pets
401 Unauthorized
WWW-Authenticate: Bearer realm="PetstoreAPI"

{
  "type": "https://petstoreapi.com/errors/authentication-required",
  "title": "Autenticación Requerida",
  "status": 401,
  "detail": "Se requieren credenciales de autenticación válidas"
}

Puntos clave:

403 Forbidden

Usar para: Usuario autenticado sin permisos.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
403 Forbidden

{
  "type": "https://petstoreapi.com/errors/insufficient-permissions",
  "title": "Permisos Insuficientes",
  "status": 403,
  "detail": "No tienes permiso para eliminar esta mascota"
}

Diferencia con 401:

404 Not Found

Usar para: El recurso no existe.

GET /pets/nonexistent-id
404 Not Found

{
  "type": "https://petstoreapi.com/errors/not-found",
  "title": "No Encontrado",
  "status": 404,
  "detail": "Mascota no encontrada"
}

No usar para: Fallos de autorización (usar 403), errores de validación (usar 400).

409 Conflict

Usar para: Conflictos de recursos como duplicados o discrepancias de versión.

POST /pets
409 Conflict

{
  "type": "https://petstoreapi.com/errors/duplicate-resource",
  "title": "Recurso Duplicado",
  "status": 409,
  "detail": "Ya existe una mascota con este ID de microchip"
}

422 Unprocessable Entity

Usar para: Formato de solicitud válido pero errores semánticos.

POST /pets
422 Unprocessable Entity

{
  "type": "https://petstoreapi.com/errors/business-rule-violation",
  "title": "Violación de Regla de Negocio",
  "status": 422,
  "detail": "No se pueden adoptar más de 5 mascotas por hogar"
}

Diferencia con 400:

429 Too Many Requests

Usar para: Límite de tasa excedido.

GET /pets
429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1678886400

{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Límite de Tasa Excedido",
  "status": 429,
  "detail": "Se excedió el límite de tasa de 100 solicitudes por hora"
}

Modern PetstoreAPI utiliza encabezados de límite de tasa de la IETF.

Códigos de Error del Servidor (5xx)

Los códigos de error del servidor indican que el servidor falló. Los clientes pueden reintentar estas solicitudes.

500 Internal Server Error

Usar para: Errores inesperados del servidor.

GET /pets
500 Internal Server Error

{
  "type": "https://petstoreapi.com/errors/internal-error",
  "title": "Error Interno del Servidor",
  "status": 500,
  "detail": "Ocurrió un error inesperado"
}

No incluir: Rastros de pila, detalles internos, errores de base de datos en producción.

503 Service Unavailable

Usar para: Indisponibilidad temporal (mantenimiento, sobrecarga).

GET /pets
503 Service Unavailable
Retry-After: 3600

{
  "type": "https://petstoreapi.com/errors/service-unavailable",
  "title": "Servicio No Disponible",
  "status": 503,
  "detail": "Servicio temporalmente no disponible por mantenimiento"
}

Incluir el encabezado Retry-After para indicar a los clientes cuándo reintentar.

Cómo Modern PetstoreAPI Usa los Códigos de Estado

Modern PetstoreAPI implementa la semántica HTTP adecuada en todos los endpoints.

Ejemplo: Gestión de Mascotas

// Listar mascotas
GET /pets
200 OK

// Crear mascota
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

// Obtener mascota
GET /pets/{id}
200 OK (encontrado) o 404 Not Found

// Actualizar mascota
PUT /pets/{id}
200 OK (con cuerpo) o 204 No Content

// Eliminar mascota
DELETE /pets/{id}
204 No Content (éxito) o 404 Not Found

Respuestas de Error

Todos los errores utilizan el formato RFC 9457:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Error de Validación",
  "status": 400,
  "detail": "La validación de la solicitud falló",
  "instance": "/pets",
  "invalid-params": [
    {
      "name": "name",
      "reason": "El nombre debe tener entre 1 y 100 caracteres"
    }
  ]
}

Consulta la documentación de manejo de errores de Modern PetstoreAPI para ver ejemplos completos.

Probando Códigos de Estado con Apidog

Apidog te ayuda a probar el comportamiento de los códigos de estado en todos los escenarios.

Definir Códigos de Estado Esperados

paths:
  /pets:
    post:
      responses:
        '201':
          description: Mascota creada
        '400':
          description: Error de validación
        '401':
          description: Autenticación requerida
        '429':
          description: Límite de tasa excedido

Probar Todos los Escenarios

Crear casos de prueba para:

Pruebas Automatizadas

// Script de prueba de Apidog
pm.test("Devuelve 201 para creación exitosa", () => {
  pm.response.to.have.status(201);
  pm.response.to.have.header("Location");
});

pm.test("Devuelve 400 para campos requeridos faltantes", () => {
  pm.response.to.have.status(400);
  pm.expect(pm.response.json().type).to.include("validation-error");
});

Errores Comunes a Evitar

Error 1: Usar 200 para POST

// Incorrecto
POST /pets
200 OK

// Correcto
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

Error 2: Usar 200 para DELETE

// Incorrecto
DELETE /pets/{id}
200 OK
{"message": "Eliminado correctamente"}

// Correcto
DELETE /pets/{id}
204 No Content

Error 3: Confundir 401 y 403

// Incorrecto: El usuario está autenticado pero carece de permisos
401 Unauthorized

// Correcto
403 Forbidden

Error 4: Usar 500 para Errores del Cliente

// Incorrecto: Un error de validación devuelve 500
POST /pets
500 Internal Server Error

// Correcto
POST /pets
400 Bad Request

Conclusión

Los códigos de estado HTTP no son opcionales. Son parte de la especificación HTTP y esenciales para construir API REST adecuadas.

Usa los códigos de estado correctos:

Modern PetstoreAPI demuestra el uso correcto de los códigos de estado en todos los endpoints. Estudia la documentación de la API REST para ver la implementación adecuada.

Prueba tus códigos de estado con Apidog para asegurarte de que tu API sigue los estándares HTTP.

Preguntas Frecuentes

¿Debo usar 200 o 204 para un DELETE exitoso?

Usa 204 No Content. Indica éxito sin un cuerpo de respuesta, ahorrando ancho de banda. Usa 200 solo si necesitas devolver información sobre el recurso eliminado.

¿Cuál es la diferencia entre 400 y 422?

400 significa que la solicitud está mal formada (JSON inválido, tipos incorrectos). 422 significa que la solicitud está bien formada pero viola las reglas de negocio.

¿Cuándo debo usar 401 vs 403?

401 significa "autentícate" (credenciales faltantes o inválidas). 403 significa "estás autenticado pero no autorizado" (permisos insuficientes).

¿Debo devolver 404 o 403 para recursos a los que los usuarios no pueden acceder?

Devuelve 403 si el recurso existe pero el usuario carece de permiso. Devuelve 404 si deseas ocultar la existencia del recurso a usuarios no autorizados.

¿Cómo pruebo todos los escenarios de códigos de estado?

Usa Apidog para crear casos de prueba para éxito, errores de validación, fallos de autenticación, no encontrados y errores del servidor. Ejecuta pruebas automatizadas en CI/CD.

¿Qué código de estado usar para el límite de tasa?

Usa 429 Too Many Requests con los encabezados RateLimit-*. Incluye Retry-After para indicar a los clientes cuándo pueden reintentar.

¿Debo usar 500 para todos los errores del servidor?

Usa 500 para errores inesperados. Usa 502 para fallos de servicios ascendentes, 503 para indisponibilidad temporal y 504 para tiempos de espera agotados.

¿Cómo maneja los errores Modern PetstoreAPI?

Todos los errores utilizan el formato RFC 9457 con los códigos de estado adecuados. Consulta la documentación de manejo de errores para ver ejemplos.

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar