Erreurs
Les corps d'erreur JSON sur `/api/v1` incluent un code machine et un message humain ; gérez 401, 403, 404, 409, 413 et 429 de façon cohérente côté client.
Les requêtes en échec renvoient du JSON avec au moins :
{
"error": "Human-readable summary",
"code": "machine_readable_code"
}
Les noms exacts des champs suivent la référence de l'API.
Cas courants
| HTTP | Cause typique | Action client |
|---|---|---|
| 401 | Jeton Bearer manquant ou invalide | Réauthentifier (OAuth) ou vérifier le PAT |
| 403 | Jeton valide mais portée ou accès ressource manquant | Afficher l'erreur de consentement/portées ; ne pas réessayer à l'aveugle |
| 404 | Portfolio ou média introuvable dans l'espace de travail | Actualiser la liste des portfolios ; vérifier les ids |
| 409 | Conflit (rejeu d'idempotence avec un corps différent) | Utiliser une nouvelle clé d'idempotence ou accepter la réponse en cache |
| 413 | Charge trop volumineuse | Réduire la taille d'export ou utiliser un téléversement reprenable quand disponible |
| 429 | Limitation de débit | Reculer et réessayer avec jitter |
UX client
Affichez error / code dans les dialogues (Lightroom) ou les journaux (scripts). N'avalez pas les erreurs API — les utilisateurs ont besoin de messages actionnables (portée manquante, portfolio introuvable, limite de stockage).