Errores
Los cuerpos de error JSON en `/api/v1` incluyen un código legible por máquina y un mensaje humano; gestiona 401, 403, 404, 409, 413 y 429 de forma coherente en los clientes.
Las peticiones fallidas devuelven JSON con al menos:
{
"error": "Human-readable summary",
"code": "machine_readable_code"
}
Los nombres exactos de los campos siguen la referencia de la API.
Casos habituales
| HTTP | Causa típica | Acción del cliente |
|---|---|---|
| 401 | Token Bearer ausente o no válido | Reautenticar (OAuth) o comprobar el PAT |
| 403 | Token válido pero falta ámbito o acceso al recurso | Mostrar error de consentimiento/ámbitos; no reintentar a ciegas |
| 404 | Portfolio o medio no encontrado en el espacio de trabajo | Actualizar la lista de portfolios; verificar ids |
| 409 | Conflicto (reintento de idempotencia duplicado con cuerpo distinto) | Usa una clave de idempotencia nueva o acepta la respuesta en caché |
| 413 | Carga demasiado grande | Reduce el tamaño de exportación o usa subida reanudable cuando esté disponible |
| 429 | Límite de tasa | Espera y reintenta con jitter |
UX del cliente
Muestra error / code en diálogos (Lightroom) o logs (scripts). No ocultes los errores de la API: los usuarios necesitan mensajes accionables (falta de ámbito, portfolio no encontrado, límite de almacenamiento).