# Fehler

> Das Fehlerformat der Tentary API, alle Fehlercodes mit HTTP-Status und wie du nach einem Fehler sicher wiederholst.

Source: https://tentary.com/de/help/api/errors/
Last updated: 2026-10-28

---

Jeder Fehler der Tentary API hat dasselbe Format. Die Nachricht sagt dir, was du tun kannst.

## Format

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

```json
{
  "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`](https://tentary.com/de/help/api/get-setup-status/). |
| 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](https://tentary.com/de/help/api/file-uploads/). |
| 429 | `rate_limited` | Zu viele Aufrufe. Der Header `Retry-After` nennt die Sekunden, die du warten sollst. Siehe [Rate Limits](https://tentary.com/de/help/api/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](https://tentary.com/de/help/api/rate-limits/#gleichzeitige-aufrufe). 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.