Fehler
JSON-Fehlerantworten unter `/api/v1` enthalten einen maschinenlesbaren Code und eine verständliche Meldung; behandeln Sie 401, 403, 404, 409, 413 und 429 in Clients einheitlich.
Fehlgeschlagene Anfragen geben mindestens folgendes JSON zurück:
{
"error": "Human-readable summary",
"code": "machine_readable_code"
}
Die genauen Feldnamen entsprechen der API-Referenz.
Häufige Fälle
| HTTP | Typische Ursache | Client-Aktion |
|---|---|---|
| 401 | Fehlendes oder ungültiges Bearer-Token | Erneut authentifizieren (OAuth) oder PAT prüfen |
| 403 | Gültiges Token, aber Berechtigungsbereich oder Ressourcenzugriff fehlt | Fehler zu Einwilligung/Berechtigungsbereichen anzeigen; nicht blind erneut versuchen |
| 404 | Portfolio oder Medium im Arbeitsbereich nicht gefunden | Portfolio-Liste aktualisieren; IDs überprüfen |
| 409 | Konflikt (doppelte Idempotenz-Wiederholung mit anderem Inhalt) | Neuen Idempotenzschlüssel verwenden oder zwischengespeicherte Antwort akzeptieren |
| 413 | Nutzlast zu groß | Exportgröße reduzieren oder resumierbaren Upload verwenden, sobald verfügbar |
| 429 | Ratenbegrenzung erreicht | Warten und mit zufälliger Verzögerung erneut versuchen |
Client-UX
Zeigen Sie error / code in Dialogen (Lightroom) oder Protokollen (Skripte) an. Unterdrücken Sie API-Fehler nicht – Benutzer benötigen umsetzbare Meldungen (fehlender Berechtigungsbereich, Portfolio nicht gefunden, Speicherlimit).