¿Cómo se diseñan responses de error consistentes y se reportan los errores de validación?

Question

IT Interview Practice · Accepted Answer

Una buena response de error hace dos cosas: usa el **HTTP status code correcto** (la señal legible por máquina), y devuelve un **body estructurado y consistente** sobre el que un desarrollador pueda actuar. Las formas de error inconsistentes son una de las mayores fuentes de dolor en el lado del client.

## Usa un formato de error estándar: RFC 7807 (problem+json)

RFC 7807 define un body estándar de "problem details" con un media type dedicado, de modo que cada error en tu API tiene el mismo aspecto:

```http
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No user exists with id 999",
  "instance": "/users/999"
}
```

- `type` — un URI que identifica la categoría del error (dereferenciable a la documentación).
- `title` — un resumen corto, legible por humanos (estable por cada `type`).
- `status` — el HTTP status, replicado por conveniencia.
- `detail` — una explicación específica de *esta* ocurrencia.
- `instance` — en qué request/recurso ocurrió.

## Errores de validación: repórtalos todos a la vez

Para la validación de formularios/fields, devuelve `422` (o `400`) y un **array de errores por field** para que el client pueda resaltar cada field incorrecto de una pasada — no un error cada vez:

```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    { "field": "email", "code": "invalid_format", "message": "must be a valid email" },
    { "field": "age",   "code": "out_of_range",   "message": "must be >= 18" }
  ]
}
```

## Principios

```text
✓ Misma forma de body para cada error (una sola ruta de código en el client)
✓ Un código estable legible por máquina (type/code) — los clients ramifican por esto, no por la prosa
✓ Mensaje legible por humanos para desarrolladores/logs
✗ Nunca filtres stack traces, SQL, o rutas internas a los clients
```

## Por qué es importante

El diseño de errores es donde las APIs silenciosamente triunfan o fracasan en el mundo real: el happy path es fácil, pero los consumidores gastan la mayor parte de su tiempo de depuración en la ruta de error, y un contrato de error inconsistente o vago hace que la integración sea miserable. Los entrevistadores usan esto para comprobar dos cosas. Primero, **el status code y el body estructurado trabajando juntos** — el status es la señal gruesa para el tooling y los retries, el body lleva el detalle accionable — en lugar del anti-patrón de `200 OK` con un error dentro. Segundo, un **código de error estable y legible por máquina** (vía el `type` de RFC 7807 o un field `code`) para que los clients puedan ramificar por `"insufficient_funds"` en lugar de comparar cadenas de un mensaje en inglés que podría reescribirse o localizarse. Devolver todos los errores de validación a la vez, y no filtrar nunca detalles internos como stack traces, redondea una respuesta que demuestra que has construido APIs que otros equipos realmente tuvieron que consumir.

Usa un formato de error estándar: RFC 7807 (problem+json)

Errores de validación: repórtalos todos a la vez

Principios

Por qué es importante

Preguntas relacionadas