HTTP Retry-After Header

Der HTTP-Header Retry-After ist ein Response-Header, der Clients mitteilt, wie lange sie warten sollen, bevor sie einen Request wiederholen. Er wird primär mit 429 Too Many Requests und 503 Service Unavailable Status-Codes verwendet für Rate-Limiting und Maintenance-Fenster.

Typ

Response-Header

Syntax

Der Header definiert Wartezeit in Sekunden oder als HTTP-Date.

http 
Retry-After: 120
Retry-After: Wed, 21 Oct 2025 07:28:00 GMT

Direktiven

Die Direktiven spezifizieren Retry-Timing als Delay oder absolute Zeit.

<delay-seconds>
Anzahl Sekunden, die Client warten soll vor erneutem Request. Ganzzahl-Wert.
<http-date>
Absoluter Zeitpunkt im HTTP-Date-Format, ab wann Client Retry versuchen darf.

Beispiele

Nachfolgend finden Sie praktische Anwendungsbeispiele für den Retry-After-Header.

Beispiel 1 Rate Limiting mit 429 Status

http 
POST /api/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1...

Server hat Rate-Limit erreicht und fordert 60 Sekunden Wartezeit.

http 
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710512400

{"error":"rate_limit_exceeded","message":"Too many requests, retry after 60 seconds"}

Client wartet 60 Sekunden vor erneutem Versuch.

Beispiel 2 Maintenance Window mit 503 Status

http 
GET /api/users HTTP/1.1
Host: api.example.com

API ist im Wartungsmodus, Server gibt Zeitpunkt für Verfügbarkeit an.

http 
HTTP/1.1 503 Service Unavailable
Retry-After: Wed, 15 Mar 2024 18:00:00 GMT
Content-Type: application/json

{"error":"maintenance","message":"Scheduled maintenance until 18:00 GMT"}

Beispiel 3 Exponential Backoff bei Server-Überlastung

http 
GET /api/reports HTTP/1.1
Host: api.example.com

Server überlastet, fordert 300 Sekunden Wartezeit.

http 
HTTP/1.1 503 Service Unavailable
Retry-After: 300
Content-Type: application/json

{"error":"service_overload","message":"High load detected, please retry after 5 minutes"}

Client implementiert Exponential Backoff (300s, 600s, 1200s).

Rate Limiting Flow

Rate Limiting mit Retry-After Header

Vorteile für die Systemarchitektur

Retry-After ermöglicht koordiniertes Backoff-Verhalten und reduziert Server-Last.

  • Koordiniertes Backoff: Clients respektieren Server-definierte Wartezeiten statt aggressiver Retries
  • Predictable Load: Server kann Last steuern durch Retry-Timing-Koordination
  • User Communication: Clients können User informierte Wartezeiten anzeigen statt generischer Fehler

Spezifikation

RFC 9110, Section 10.2.3 – HTTP Semantics https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after

Weitere Spezifikationen

HTTP Status 503 - Service Unavailable, HTTP Status 429 - Too Many Requests