# Fehler

> Ein maschinenlesbares Problemdokument für jeden Fehlschlag und was jeder Typ für Ihre Retry-Logik bedeutet.

Source: https://developers.backresto.com/de/docs/errors

Jeder Fehlschlag (auch eine Route, die es nicht gibt) antwortet mit
`application/problem+json`, der in RFC 9457 definierten Struktur. Es gibt keinen
Weg durch diese API, der eine HTML-Fehlerseite zurückgibt; ein Parser, der bei
einer Antwort außerhalb von 2xx JSON annimmt, ist also sicher.

```json
{
  "type": "https://api.backresto.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The authenticated client lacks the required scope.",
  "instance": "/v1/restaurants/restaurant-1/collections/delivery-pictures/records/8f2c/assets",
  "requestId": "b1c8b0a4-6c1e-4f6b-9e1c-3b2a5d7f0e91"
}
```

`type` ist die stabile Kennung: Verzweigen Sie darauf, nicht auf `detail`, das
Prosa ist und umformuliert werden kann. `requestId` ist der Wert, den Sie in
einer Support-Nachricht nennen sollten. Er wird auch im Antwort-Header
`X-Request-ID` zurückgegeben, und Sie können diesen Header selbst setzen, um mit
Ihren eigenen Traces zu korrelieren.

## Der Katalog

| `type`-Suffix | Status | Was passiert ist | Erneut versuchen? |
| --- | --- | --- | --- |
| `invalid-request` | 400 | Ein Parameter fehlt oder ist fehlerhaft: ein `limit` außerhalb des Bereichs, eine unbekannte Collection oder ein Cursor, der nicht zu dem Restaurant, der Collection und dem `limit` passt, mit denen Sie blättern. | Nein. Korrigieren Sie die Anfrage. |
| `unauthorized` | 401 | Kein `Authorization`-Header, oder ein Schlüssel, der fehlerhaft, unbekannt, widerrufen oder abgelaufen ist oder gar keine Zuweisung mehr hat. | Nein. Der Schlüssel braucht Aufmerksamkeit. |
| `forbidden` | 403 | Der Schlüssel hat eine Zuweisung für dieses Restaurant, aber nicht den Scope, den dieser Endpunkt braucht. | Nein. Es muss ein Schlüssel mit diesem Scope angefragt werden. |
| `not-found` | 404 | Keine Zuweisung für dieses Restaurant, oder es gibt diesen Datensatz nicht. Die Fälle sind bewusst nicht unterscheidbar. | Nein. |
| `conflict` | 409 | Die Anfrage steht im Konflikt mit einer bestehenden Ressource. | Nein. |
| `payload-too-large` | 413 | Der Request-Body überschreitet das Limit. | Nein. |
| `rate-limit-exceeded` | 429 | Ihr Client hat sein Anfragebudget überschritten. | Ja, nach `Retry-After`. |
| `dependency-unavailable` | 503 | Eine Komponente, die die API braucht, ist kurzzeitig nicht verfügbar. | Ja, mit Backoff. |
| `internal-error` | 500 | Ein unerwarteter Fehler, bei uns bereits protokolliert. | Einmal, mit Backoff; dann nennen Sie uns die `requestId`. |

## Was ein Client tun sollte

Drei Kategorien, und mehr ist den Code nicht wert:

**Nicht erneut versuchen**: 400, 401, 403, 404, 409, 413. Die Anfrage wird
identisch erneut fehlschlagen. Protokollieren Sie `type` und `requestId` und
machen Sie es sichtbar: Ein `401` bedeutet insbesondere, dass ein Mensch auf
Kundenseite etwas widerrufen hat, und eine Retry-Schleife verdeckt das nur eine
Woche lang.

**Mit Backoff erneut versuchen**: 429, 503. Halten Sie sich bei einem 429 an
`Retry-After`; das ist die Anzahl der Sekunden, bis sich Ihr Budget wieder
füllt, und es ist kein Vorschlag. Bei 503 exponentielles Backoff mit Jitter, und
geben Sie lieber auf, statt zu hämmern.

**Einmal erneut versuchen, dann eskalieren**: 500. Tritt es bei derselben
Anfrage wieder auf, ist es nicht vorübergehend.

Jeder Endpunkt dieser API ist ein `GET`, aus Sicht der API ist ein erneuter
Versuch also immer unbedenklich; der Grund, einen 4xx nicht zu wiederholen, ist,
dass er Ihr Budget verbraucht, nicht dass er einen doppelten Schreibvorgang
riskiert.

## Mit Ihren eigenen Logs korrelieren

Senden Sie Ihre eigene Kennung, und sie kommt zurück:

```bash
curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/collections/deliveries/records?limit=100" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY" \
  -H "X-Request-ID: 3f7a1c9e-2b4d-4a86-9f0c-5e1d8b6a2c40" \
  --include
```

Der Wert wird im Antwort-Header und in der `requestId` eines Problemdokuments
gespiegelt, sodass ein einziges grep die Frage beantwortet: „Was hat BackResto
gesehen, als mein Job um 04:12 fehlgeschlagen ist?“