Hoja de trucos de API RESTful

REST (Representational State Transfer) es un estilo arquitectónico para diseñar servicios API web en red sobre HTTP.

Verbos HTTP y semántica

---

Códigos de estado HTTP comunes

Éxito (2xx)

• 200 OK: Solicitud exitosa (el cuerpo contiene la representación).
• 201 Created: Recurso creado correctamente (la cabecera Location indica el URI).
• 202 Accepted: Solicitud aceptada para procesamiento asíncrono.
• 204 No Content: Acción exitosa, sin cuerpo de respuesta (común en DELETE).

Errores de cliente (4xx)

• 400 Bad Request: Sintaxis malformada, parámetros inválidos o fallo de validación.
• 401 Unauthorized: Falta autenticación o es inválida.
• 403 Forbidden: Usuario autenticado sin permisos para acceder al recurso.
• 404 Not Found: El URI del recurso no existe.
• 409 Conflict: La solicitud entra en conflicto con el estado actual del recurso (p. ej., clave única duplicada).
• 422 Unprocessable Entity: Solicitud bien formada que falló la validación semántica del dominio.
• 429 Too Many Requests: Límite de tasa (Rate Limit) excedido.

Errores de servidor (5xx)

• 500 Internal Server Error: Fallo genérico no controlado en el servidor.
• 502 Bad Gateway: El servidor ascendente (Upstream) devolvió una respuesta inválida.
• 503 Service Unavailable: Servidor sobrecargado o en mantenimiento.

---

Formato estándar de error JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The email address provided is already registered.",
    "details": [
      {
        "field": "email",
        "issue": "unique_constraint_violated"
      }
    ]
  }
}

---

Referencias

• Hoja de trucos de códigos de estado HTTP
• RFC 9110: Semántica HTTP