Errores y problemas (RFC 9457)

• Tipo de contenido: `application/problem+json`
• Esquema: `components.schemas.Problem` en

`packages/contracts/openapi.yaml`

Los errores de la API siguen Problem Details de RFC 9457. Un problema incluye,
como mínimo, `type`, `title` y `status`; normalmente también `detail` e
`instance`. Decide con el código HTTP y, cuando la operación lo declare, con
`type`. Muestra `detail` al usuario solo cuando corresponda a tu interfaz.

Ejemplo de forma:

{
  "type": "https://cerca.red/problems/404",
  "title": "No encontrado",
  "status": 404,
  "detail": "No se encontró el recurso.",
  "instance": "/v1/businesses/ejemplo"
}

Casos frecuentes:

• `400`: cuerpo, parámetro o cabecera con forma inválida.
• `401`: no hay sesión válida.
• `403`: falta reautenticación, aceptación legal o permiso.
• `404`: el recurso o la relación solicitada no existe para quien la pide.
• `409`: conflicto de estado, por ejemplo una ficha ya reclamada.
• `412`: el `If-Match` ya no coincide; vuelve a leer antes de guardar.
• `428`: falta `If-Match` en una operación que lo exige.
• `429`: espera el tiempo indicado por `Retry-After` si la respuesta lo trae.
• `503`: falta una configuración propia de la operación o un proveedor no está

disponible; no inventes un valor de reemplazo.

No conviertas cualquier `detail` en una regla permanente. Los tipos de problema
de cada operación están declarados en OpenAPI y pueden distinguir dos errores con
el mismo código HTTP.