Fehler

Format

Jeder Fehler kommt als JSON mit einem passenden HTTP-Status:

{
  "error": {
    "code": "...",
    "message": "...",
    "request_id": "..."
  }
}

• code ist ein fester Wert aus der Tabelle unten. Darauf kann dein Code reagieren.
• message beschreibt in Worten, was falsch ist und was du tun kannst.
• request_id identifiziert die Anfrage. Schick sie an den Support, wenn du Hilfe brauchst.

Zwei Antworten haben einen kürzeren Body: Ein unerwarteter Serverfehler antwortet mit {"error": "server_error", "request_id": "..."}, ein Pfad außerhalb von /v1/ mit {"error": "not_found"}.

Fehlercodes

HTTP	code	Bedeutung
400	bad_input	Ein Parameter fehlt, ist unbekannt oder falsch. Die Nachricht nennt ihn.
400	bad_cursor	Der Cursor ist ungültig. Fang ohne Cursor neu an.
400	bad_image	Die Datei oder die URL ist kein Bild im Format PNG, JPG, GIF oder WebP.
400	fetch_failed	Tentary konnte die Datei nicht von der URL kopieren, zum Beispiel weil die Datei zu groß ist oder die URL nicht mit HTTP 200 antwortet. Die Nachricht sagt, warum.
400, 404	legacy_course	Das Produkt hat einen alten Kurs. Öffne ihn zuerst einmal in der Tentary-App. Die Nachricht enthält den Link.
400	not_possible	Die Aktion ist für dieses Objekt nicht möglich, zum Beispiel die Erstattung einer alten Bestellung.
400, 403	setup_missing	Die Einrichtung des Kontos ist nicht fertig, zum Beispiel fehlt ein Zahlungsanbieter. Siehe GET /v1/setup.
401	unauthorized, invalid_token	Kein Schlüssel, ein falscher oder ein entzogener Schlüssel. Die Antwort hat den Header WWW-Authenticate: Bearer.
403	scope_missing	Dem Schlüssel fehlt die Berechtigung. Lege einen Schlüssel mit dieser Berechtigung an.
403	owner_only, blocked, plan_limit, not_possible	Für dieses Konto nicht erlaubt oder über die API nicht möglich. Die Nachricht sagt, warum.
404	not_found	Dieses Objekt gibt es in diesem Konto nicht, oder den Pfad gibt es nicht.
405	method_not_allowed	Falsche HTTP-Methode. Der Header Allow nennt die richtige.
409	busy	Dieselbe Änderung läuft noch, oder Tentary kopiert dieses Produkt noch. Warte eine Minute, prüfe, dann wiederhole.
409	not_uploaded	Die Datei ist noch nicht im Speicher. Schick die Bytes zuerst mit PUT an die upload_url und schließ den Upload dann noch einmal ab. Siehe Uploads.
429	rate_limited	Zu viele Aufrufe. Der Header Retry-After nennt die Sekunden, die du warten sollst. Siehe Rate Limits.
429	busy	Zu viele Aufrufe dieses Kontos laufen gleichzeitig, oder Tentary kopiert gerade eine andere Datei oder ein anderes Bild dieses Kontos. Siehe Rate Limits. Warte die Sekunden aus Retry-After, dann wiederhole.
500	server_error	Ein Fehler bei Tentary. Schick die request_id an den Support.
503	timeout	Der Aufruf hat für dieses Konto zu lange gedauert. Frag einen kürzeren Zeitraum, ein Produkt (product_id) oder weniger Einträge pro Seite ab.
503	unavailable	Die Suche im Hilfecenter ist gerade nicht verfügbar. Versuch es später noch einmal.

Sicher wiederholen

• Nach einem 429 wartest du die Sekunden aus Retry-After. Wiederhole nicht sofort in einer Schleife: Auch ein Aufruf, den das Minuten- oder Tageslimit abweist, kostet 1 Punkt.
• Nach einem Timeout oder einem 500 bei einer Änderung liest du zuerst das Objekt oder die Liste, um zu sehen, ob die Änderung schon passiert ist. Erst dann wiederholst du.
• Anlegen-Aufrufe (und POST /v1/files) haben einen kurzen Schutz: Dasselbe Anlegen mit denselben Werten innerhalb von 60 Sekunden liefert das erste Ergebnis zurück und legt kein zweites Objekt an. Das ist keine allgemeine Garantie. Änderungen und Aufrufe nach 60 Sekunden laufen erneut.