Fehler

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

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.

{
  "type": "https://api.backresto.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The authenticated client lacks the required scope.",
  "instance": "/v1/restaurants/restaurant-1/deliveries/8f2c/images",
  "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 verkehrt herum liegender oder zu langer Lieferzeitraum, 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 die Berechtigung, die dieser Endpunkt braucht.	Nein — der Kunde muss einen Schlüssel mit dieser Berechtigung ausstellen lassen.
`not-found`	404	Keine Zuweisung für dieses Restaurant, oder es gibt diese Lieferung oder 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 Anfragerumpf überschreitet das Limit.	Nein.
`rate-limit-exceeded`	429	Ihr Client hat sein Anfragebudget überschritten.	Ja, nach `Retry-After`.
`dependency-unavailable`	503	Eine Komponente, welche 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:

curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/deliveries?from=1787846400000&to=1787932800000" \
  -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?“.