Fehler bewusst behandeln

Was einen erneuten Versuch lohnt

Verzweigen Sie über error.reason, nie über die Meldung: Gründe sind stabil und werden nie umbenannt, Meldungen sind für Menschen geschrieben. Die Fehlerseite listet jeden davon.

Was durch Wiederholung nicht gelingt

Das sind Antworten, keine Störungen. Sie zu wiederholen kostet Anfragen für denselben Satz, und in einer Schleife erreicht ein Schlüssel so bis mittags sein Tageslimit.

401 betrifft die Zugangsdaten, 403 das Erlaubte. Ein neuer Schlüssel behebt das Erste und ändert am Zweiten nichts. Authentifizierung zieht die Linie vollständig.

Eine Wiederholungsschleife mit Manieren

Drei Regeln: nur wiederholbare Gründe, das serverseitige Retry-After wo gesendet, und Jitter, damit eine Flotte, die gemeinsam gescheitert ist, nicht gemeinsam wiederholt. Ein verbrauchtes Tages- oder Monatskontingent ist die Ausnahme: warten Sie nur, wenn sein Reset Sekunden entfernt ist, sonst halten Sie an.

1// Retry the failures that can succeed later, and only those.2const RETRYABLE = new Set(['RATE_LIMITED', 'PAGINATION_BURST', 'DAILY_CAP_EXCEEDED', 'MONTHLY_CAP_EXCEEDED', 'DEPENDENCY_UNAVAILABLE', 'MAINTENANCE', 'INTERNAL_ERROR'])3 4// A spent daily or monthly allowance resets at midnight UTC or on the 1st.5// Wait for it only when it is seconds away, as the SDKs do (30 seconds by6// default). Never sleep through a day or a month.7const ALLOWANCES = new Set(['DAILY_CAP_EXCEEDED', 'MONTHLY_CAP_EXCEEDED'])8const MAX_WAIT_SECONDS = 309 10async function call(request, attempt = 0) {11  const res = await fetch(request)12  if (res.ok) return res13 14  const body = await res.json().catch(() => null)15  const reason = body?.error?.reason16 17  // A reason the API says is permanent. Sending it again is a18  // request spent to receive the same sentence.19  if (!RETRYABLE.has(reason) || attempt >= 4) throw new GunSpecError(res.status, body)20 21  // Honour the server's own number when it sends one: it knows when22  // the window resets and a guess does not.23  const retryAfter = Number(res.headers.get('Retry-After')) || 024 25  // The allowance is spent and the reset is far off. Nothing is served26  // before it, so sleeping here is a stuck request, not a retry. Stop, and27  // run the work again after the instant the API names.28  if (ALLOWANCES.has(reason) && retryAfter > MAX_WAIT_SECONDS) {29    throw new LimitReached(reason, body.error.resetsAt)30  }31 32  const backoff = retryAfter * 1000 || 2 ** attempt * 50033 34  // Jitter, or every client that failed together retries together.35  await sleep(backoff + Math.random() * 250)36  return call(request, attempt + 1)37}

Die offiziellen SDKs tun das bereits: maxRetries steht auf 2, Retry-After wird bis maxRetryAfterMs beachtet (eine Ablehnung, deren Reset weiter entfernt ist, wird sofort als Fehler ausgelöst und nie ausgesessen), und jeder Fehler trägt reason und requestId. Stellen Sie es über retry am Client ein, statt es zu umwickeln. Siehe die SDK-Referenz.

Was die Leser währenddessen sehen

Eine Seite, die ohne unsere Daten rendert, ist besser als eine, die gar nicht rendert. Entscheiden Sie das einmal an der Grenze, nicht in jeder Komponente.

1// What the reader sees while this is going wrong.2try {3  return await gunspec.firearms.get(id)4} catch (err) {5  // A copy from ten minutes ago is a better page than an error, and6  // the catalog changes on the order of days.7  const stale = await cache.get(id)8  if (stale) return { ...stale, stale: true }9 10  // Nothing cached. Say what failed, quote the request id, and let11  // the page render the rest of itself.12  logger.warn({ requestId: err.requestId, reason: err.reason }, 'gunspec unavailable')13  return null14}

• Liefern Sie eine veraltete Kopie, bevor Sie einen Fehler liefern. Der Katalog bewegt sich in Tagen, also sind zehn Minuten alte Daten keine Lüge.
• Lassen Sie einen Abschnitt scheitern, nicht die Seite: nicht erreichbare Händler dürfen die Datentabelle nicht mitnehmen.
• Setzen Sie jedem Aufruf ein Timeout. Eine Anfrage, die nie zurückkehrt, ist schlimmer als eine, die scheitert, weil danach nichts mehr entscheiden kann.
• Wiederholen Sie einen Schreibvorgang nie nur wegen einer langsamen Antwort, solange Sie keine Idempotenz haben. Ein Duplikat ist ein echter Schaden, eine Verzögerung nicht.

Wenn es an uns liegt

Jede Antwort trägt X-Request-Id, und jeder SDK-Fehler trägt sie als requestId. Protokollieren Sie sie. Damit finden wir genau diese Anfrage; ohne sie ist eine Meldung die Beschreibung einer Seite. Support und Feedback ist der Weg dorthin.