Der Retry-After-Header: wie lange gewartet werden soll, bevor Sie den Vorgang wiederholen

Retry-After ist ein HTTP-Antwortheader, der Ihrer App angibt, wie lange gewartet werden soll, bevor sie die nächste Anforderung sendet. Der Wert ist entweder eine Anzahl von Sekunden oder ein HTTP-Datum. Wenn er von einer API gesendet wird, ist dies die zuverlässigste Antwort auf die Frage „Wann kann ich es erneut versuchen?“, da er von dem Server stammt, der Ihre Anfrage abgelehnt hat. Weitere Informationen finden Sie unter RFC 9110, Abschnitt 10.2.3.

Wie Retry-After aussieht

Die Kopfzeile hat 2 Formate. Ihre App muss beides verarbeiten.

Format Example Was dies bedeutet
Seconds Retry-After: 120 Warten Sie 120 Sekunden (2 Minuten) ab dem Zeitpunkt, zu dem Sie die Antwort erhalten haben. Der Wert ist eine nicht negative ganze Zahl.
HTTP-Datum Retry-After: Fri, 31 Dec 1999 23:59:59 GMT Senden Sie die Anfrage vor diesem Zeitpunkt nicht erneut. Das Datum wird immer in GMT angezeigt.

Server senden Retry-After mit diesen Statuscodes:

Status Die Bedeutung von Retry-After Source
429 Too Many Requests Wie lange warten, bevor Sie eine neue Anforderung senden. Der Server kann es enthalten. RFC 6585, Abschnitt 4
503 Service Unavailable Wie lange der Dienst voraussichtlich nicht verfügbar ist. Der Server kann es enthalten. RFC 9110, Abschnitt 15.6.4
413 Content Too Large Bei einer temporären Bedingung sollte der Server angeben, wie lange der Zustand noch andauert. RFC 9110, Abschnitt 15.5.14
Beliebige 3xx-Umleitung Die minimale Wartezeit, bevor Sie der Umleitung folgen. RFC 9110, Abschnitt 10.2.3

Die Kopfzeile ist optional. Einige APIs verwenden stattdessen eigene Header. Beispielsweise informiert GitHub Sie, wenn Ihr Grenzwert zurückgesetzt wird.x-ratelimit-reset Weitere Informationen finden Sie unter GitHub API-Ratelimit überschritten.

Behandeln von Retry-After

  1. Lesen Sie beide Formate. Wenn der Wert eine Zahl ist, wird sie in Sekunden angegeben. Interpretieren Sie sie andernfalls als Datum, und subtrahieren Sie den aktuellen Zeitpunkt. Wenn sich das Datum bereits in der Vergangenheit befindet, können Sie den Vorgang sofort wiederholen.
  2. Warten Sie mindestens so lange, wie im Header angegeben. Wenn Sie es früher erneut versuchen, erhalten Sie in der Regel eine andere 429 oder 503. Einige APIs zählen Ihre Anfragen, während sie Sie drosseln, sodass frühe Wiederholungen die Wartezeit verlängern können. Informationen dazu finden Sie beispielsweise unter Anleitung zur Drosselung bei Microsoft Graph.
  3. Führen Sie bei fehlendem Header ein Fallback zum Backoff mit Jitter durch. Verdoppeln Sie die Wartezeit nach jedem fehlgeschlagenen Versuch, fügen Sie einen zufälligen Betrag hinzu, sodass viele Clients nicht zur gleichen Zeit erneut versuchen, und begrenzen Sie die Wartezeit.
  4. Begrenzen Sie Ihre Wiederholungsversuche. Geben Sie nach einigen Versuchen den Fehler an den Aufrufer zurück.
  5. Überprüfen Sie, ob ein Wiederholungsversuch hilfreich sein kann. Einige APIs geben 429 zurück, wenn Ihr Guthaben oder Ihre Ausgabenbegrenzung aufgebraucht ist. Durch Warten wird das nicht behoben. Ein Beispiel finden Sie unter OpenAI insufficient_quota und credit_balance_exhausted.
function retryDelayMs(response, attempt) {
  const value = response.headers.get('retry-after');
  if (value) {
    const seconds = Number(value);
    const ms = Number.isNaN(seconds) ? Date.parse(value) - Date.now() : seconds * 1000;
    if (!Number.isNaN(ms)) {
      return Math.max(ms, 0);
    }
  }
  // No usable header: exponential backoff with jitter, capped at 30 seconds
  return Math.random() * Math.min(30_000, 1_000 * 2 ** attempt);
}

Viele SDKs übernehmen Retry-After für Sie, aber nur, bis ihnen die Wiederholungsversuche ausgehen. Dann tritt in Ihrem Code der Fehler auf.

SDK Die standardmäßige Funktionsweise
.NET Standardresilienzhandler Wiederholt 408, 429und 5xx-Antworten bis zu 3 Mal mit exponentiellem Backoff und Jitter. Es verwendet Retry-After für die Verzögerung, da ShouldRetryAfterHeader standardmäßig true ist.
Microsoft Graph SDKs Verwenden Sie Retry-After, wenn es vorhanden ist, und greifen Sie andernfalls auf exponentielles Backoff zurück. Anforderungen innerhalb eines JSON-Batches werden nicht automatisch wiederholt.
OpenAI Python SDK Wiederholt bei Verbindungsfehlern und 408, 409, 429 sowie 5xx-Antworten 2 Mal mit einem kurzen exponentiellen Backoff. Legen Sie zum Ändern max_retries fest.

Überprüfen Sie die Dokumentation Ihres SDK auf die genaue Richtlinie, und testen Sie, was nach dem letzten Wiederholungsversuch passiert.

So testen Sie, ob Ihre App Retry-After verarbeitet

Sie erhalten selten eine Retry-After, während der Entwicklung, und wenn doch, können Sie ihren Wert nicht steuern. Die Art und Weise, wie Sie dies testen, entscheidet also, ob Sie die Fehler finden, bevor Ihre Benutzer dies tun.

Approach Was Sie finden Was Sie verpassen
Auf die Produktion warten Tatsächliche Fehler Alles, bis ein Benutzer darauf klickt
Mocken Sie die API in Ihren Tests, oder lassen Sie Ihren Coding-Agenten den Mock schreiben Ob Ihr Code den Header analysiert Ob Ihr tatsächlicher HTTP-Client oder Ihr SDK lange genug wartet und was die API wirklich sendet. Ihre App benötigt außerdem einen reinen Testschalter, um den Mock zu erreichen.
Die tatsächliche API aufrufen, bis sie Sie drosselt Tatsächliches Verhalten Sie können keine gedrosselte Antwort bei Bedarf auslösen, und Sie brauchen Ihr tatsächliches Kontingent auf.
Fangen Sie den tatsächlichen Datenverkehr Ihrer App ab und geben Sie bei Bedarf gedrosselte Antworten zurück Ob Ihr tatsächliches SDK und Ihre Wiederholungsstrategie so lange warten, wie im Header angegeben An Ihrer App ändert sich nichts, daher wird Ihr Code nicht isoliert getestet. Bewahren Sie sich das für Unit-Tests auf.

Testen Sie es in Ihrer App

Dev Proxy fängt die Anforderungen Ihrer App bei den von Ihnen ausgewählten APIs ab 429 und gibt 503-Antworten mit einem Retry-After-Header zurück, während Ihre App die tatsächlichen URLs aufruft. Das RetryAfterPlugin speichert, wann jede gedrosselte Anfrage erneut versucht werden kann. Wenn Ihre App vor diesem Zeitpunkt dieselbe URL aufruft, meldet Dev Proxy dies und drosselt die Anfrage erneut.

Legen Sie in der Fehlerdatei für GenericRandomErrorPlugin den Retry-After Wert einer Antwort auf @dynamic fest, und Dev Proxy trägt die Anzahl der Sekunden ein und protokolliert sie für Sie. Dies funktioniert mit jedem Statuscode, wie 429 oder 503.

Um es auszuprobieren, laden Sie eine Voreinstellung herunter, die beide Plugins verwendet, und starten Sie Dev Proxy damit:

devproxy config get openai-throttling
devproxy --config-file "~dataFolder/configs/openai-throttling/.devproxy/devproxyrc.json"

Führen Sie dann Ihre App wie gewohnt aus, und beobachten Sie, was sie tut. Informationen zum Installieren von Dev Proxy finden Sie unter Einrichten von Dev Proxy.

Nächste Schritte

Teste, ob meine Anwendung die Drosselung korrekt behandelt

Siehe auch

  • Zuletzt aktualisiert um