Web & Entwicklung

Wie man API-Zeitüberschreitungen, Ratenbegrenzungen und Wiederholungen in PHP behandelt

How to Handle API Timeouts, Rate Limits, and Retries in PHP

Lernen Sie, wie Sie zuverlässige PHP-API-Integrationen mit Verbindungszeitüberschreitungen, HTTP-Fehlerbehandlung, exponentiellem Backoff, Retry-After-Unterstützung und sicheren Wiederholungsstrategien erstellen.

Wie API-Timeouts, Rate Limits und Retries in PHP handhaben

Eine API-Integration funktioniert während der Entwicklung perfekt. Dann, eines Tages, bricht Ihr geplanter Auftrag mittendrin ab. Ein Fernservice gibt HTTP 429 zurück, eine Verbindung zeitoutet, oder ein HTTP-503-Fehler unterbricht eine Synchronisierung.

Die Versuchung ist, die Anforderung sofort erneut zu senden. Ohne Strategie kann das Problem verschlimmern. Es kann einen bereits kämpfenden API überlasten, Rate-Limits überschreiten oder versehentlich doppelte Bestellungen und Zahlungen erzeugen.

Ein zuverlässiger API-Client braucht mehr als einen erfolgreichen curl_exec()-Aufruf.

In diesem Tutorial bauen wir einen praktischen PHP-HTTP-Client, der Verbindungs-Timeouts, HTTP-Fehler, Rate-Limits und vorübergehende Fehler verarbeitet. Wir erklären auch, wann das erneute Senden sicher ist, wann nicht und wie man Probleme in der Produktion diagnostiziert.

Die Beispiele nutzen die eingebaute cURL-Erweiterung von PHP, ohne Composer oder Drittanbieter-Abhängigkeiten.

1. Verstehen der verschiedenen Arten von API-Fehlern

Nicht jede fehlgeschlagene Anforderung sollte gleich behandelt werden.

Failure Typical cause Recommended action
Connection timeout Server unreachable or slow connection Retry cautiously
HTTP 400 Invalid request parameters Fix the request
HTTP 401 Invalid or expired credentials Check authentication
HTTP 404 Resource not found Check resource identifier
HTTP 429 API rate limit exceeded Respect Retry-After
HTTP 500 Internal server error Retry selectively
HTTP 503 Temporary service unavailability Retry with delay
Invalid JSON Unexpected response format Log and investigate

Ein Netzwerkfehler ist auch anders als ein HTTP-Fehler.

Wenn eine API HTTP 500 zurückgibt, wurde die HTTP-Anfrage abgeschlossen und der Server gab einen Fehlerantwort zurück.

Wenn cURL einen Verbindungsfehler meldet, hat Ihre Anwendung möglicherweise gar keine HTTP-Antwort erhalten.

Diese Unterscheidung ist wichtig, wenn entschieden wird, ob wiederholt wird.

2. Immer Verbindungs- und Anfrage-Timeouts konfigurieren

PHP cURL bietet zwei besonders nützliche Einstellungen:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT begrenzt die Verbindungsphase, während CURLOPT_TIMEOUT die Gesamtdauer des Transfers begrenzt. Beide sind in der offiziellen PHP-cURL-Referenz dokumentiert.

Ohne geeignete Limits kann ein langsamer externer Dienst PHP-Worker viel länger beschäftigen als erwartet.

Ein praktischer Ausgangspunkt für einen konventionellen JSON-API könnte fünf Sekunden für die Verbindungsherstellung und fünfzehn Sekunden für die komplette Anforderung sein.

Diese sind keine universellen Werte. Einen Dateiupload oder langlaufende Berichtserstellung may need a different timeout policy.

Ihre erste API-Anforderung machen

<?php
declare(strict_types=1);

$url = 'https://api.example.com/products';

$curl = curl_init($url);

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_FOLLOWLOCATION => false,
]);

$response = curl_exec($curl);
$statusCode = curl_getinfo(
    $curl,
    CURLINFO_HTTP_CODE
);

if ($response === false) {
    $error = curl_error($curl);

    curl_close($curl);

    throw new RuntimeException(
        'API request failed: ' . $error
    );
}

curl_close($curl);

echo 'HTTP status: ' . $statusCode;

Dies legt eine nützliche Grundlage, handelt aber noch nicht mit Rate-Limits oder wiederholbaren Fehlern.

3. HTTP 429 und Retry-After verstehen

HTTP 429 bedeutet, dass der Client zu viele Anfragen innerhalb einer vom API-Anbieter definierten Periode gesendet hat.

Einige APIslegen Limits pro Minute, pro Stunde, pro API-Schlüssel oder pro Konto fest.

Ein Server kann mit folgendem antworten:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

Der Retry-After-Header teilt dem Client mit, wie lange es warten sollte, bevor es erneut versucht.

Der Header kann entweder eine Zahl von Sekunden oder ein HTTP-Datum enthalten.

Zum Beispiel:

Retry-After: 120

Oder:

Retry-After: Wed, 25 Nov 2026 10:00:00 GMT

Ein gut erzogener Client sollte dieser Anweisung folgen, anstatt wiederholt Anfragen zu senden.

Wenn der Server keinRetry-Delay bereitstellt, benötigt Ihre Anwendung eine Strategie für den Fallback.

4. Exponentielles Backoff anstelle von sofortigen Wiederholungen verwenden

Exponentielles Backoff erhöht die Wartezeit nach aufeinanderfolgenden Fehlern.

Zum Beispiel:

Retry Example delay
1 1 second
2 2 seconds
3 4 seconds
4 8 seconds

Anstatt jede Sekunde erneut zu versuchen, wartet die Anwendung progressive länger.

Eine kleine zufällige Variation, genannt Jitter, verhindert, dass viele Clients gleichzeitig wiederholen.

Hier ist eine wiederverwendbare Verzögerungsfunktion:

<?php
declare(strict_types=1);

function getRetryDelayMs(int $attempt): int
{
    $baseDelay = 1000;
    $maximumDelay = 30000;

    $exponentialDelay = min(
        $maximumDelay,
        $baseDelay * (2 ** ($attempt - 1))
    );

    return random_int(
        0,
        (int)$exponentialDelay
    );
}

Dieser verwendet vollständiges Jitter: die tatsächliche Verzögerung wird zufällig zwischen null und dem exponentiellen Grenzwert selected.

Die zufällige Verzögerung reduziert synchronisierte Wiederholungsbursts, obwohl sie kein explizit server-providierten Retry-After-Anweisung ersetzt.

5. Wiederverwendbaren PHP-API-Client bauen

Lassen Sie uns die vorherigen Konzepte zu einer Arbeitsimplementation kombinieren.

Unser Client wird:

  • Festlegen von Verbindungs- und Gesamt-Timeouts.
  • Rückgabe des HTTP-Status und Antworttext.
  • Erkennen von Transport-Fehlern.
  • Ausgewählte vorübergehende Fehler wiederholen.
  • Retry-After bei vorhanden Respektieren.
  • Begrenzen der Anzahl der Versuche.
  • Automatisches Wiederholen von nicht-idempotenten Operationen vermeiden.
<?php
declare(strict_types=1);

/**
 * Perform an HTTP GET request with bounded retries.
 *
 * Use only with trusted, configured API URLs.
 */
function apiGet(
    string $url,
    int $maxAttempts = 3
): array {
    if ($maxAttempts < 1) {
        throw new InvalidArgumentException(
            'maxAttempts must be at least 1.'
        );
    }

    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        $headers = [];

        $curl = curl_init($url);

        if ($curl === false) {
            throw new RuntimeException(
                'Unable to initialize cURL.'
            );
        }

        curl_setopt_array($curl, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CONNECTTIMEOUT => 5,
            CURLOPT_TIMEOUT => 15,
            CURLOPT_FOLLOWLOCATION => false,
            CURLOPT_HTTPGET => true,
            CURLOPT_HEADERFUNCTION => static function (
                $curl,
                string $headerLine
            ) use (&$headers): int {
                $length = strlen($headerLine);

                if (str_starts_with(
                    $headerLine,
                    'HTTP/'
                )) {
                    $headers = [];
                }

                $position = strpos(
                    $headerLine,
                    ':'
                );

                if ($position !== false) {
                    $name = strtolower(trim(
                        substr($headerLine, 0, $position)
                    ));

                    $value = trim(
                        substr($headerLine, $position + 1)
                    );

                    $headers[$name] = $value;
                }

                return $length;
            },
        ]);

        $body = curl_exec($curl);
        $curlError = curl_errno($curl);
        $statusCode = (int)curl_getinfo(
            $curl,
            CURLINFO_HTTP_CODE
        );

        curl_close($curl);

        $transportFailure = $body === false;

        $retryableStatus = in_array(
            $statusCode,
            [408, 429, 500, 502, 503, 504],
            true
        );

        if (!$transportFailure && !$retryableStatus) {
            return [
                'status' => $statusCode,
                'body' => $body,
                'headers' => $headers,
                'attempts' => $attempt,
            ];
        }

        if ($attempt === $maxAttempts) {
            throw new RuntimeException(
                'API request failed after '
                . $attempt
                . ' attempts. HTTP '
                . $statusCode
                . ', cURL error '
                . $curlError
            );
        }

        $delayMs = min(
            30000,
            1000 * (2 ** ($attempt - 1))
        );

        $retryAfter = $headers['retry-after'] ?? null;

        if ($retryAfter !== null) {
            if (ctype_digit($retryAfter)) {
                $delayMs = (int)$retryAfter * 1000;
            } else {
                $timestamp = strtotime($retryAfter);

                if ($timestamp !== false) {
                    $delayMs = max(
                        0,
                        $timestamp - time()
                    ) * 1000;
                }
            }
        } else {
            $delayMs = random_int(
                0,
                (int)$delayMs
            );
        }

        // Do not block this worker indefinitely.
        if ($delayMs > 30000) {
            throw new RuntimeException(
                'Retry deferred: waiting time exceeds '
                . 'the synchronous retry budget.'
            );
        }

        usleep((int)$delayMs * 1000);
    }

    throw new RuntimeException(
        'Unexpected retry state.'
    );
}

Wie man es verwendet

<?php
declare(strict_types=1);

try {
    $result = apiGet(
        'https://api.example.com/products'
    );

    if ($result['status'] !== 200) {
        throw new RuntimeException(
            'Unexpected HTTP status: '
            . $result['status']
        );
    }

    $products = json_decode(
        $result['body'],
        true,
        512,
        JSON_THROW_ON_ERROR
    );

    echo 'API request completed after '
        . $result['attempts']
        . ' attempt(s).';

} catch (Throwable $exception) {
    error_log($exception->getMessage());
}

Diese Implementation ist absichtlich auf GET-Anfragen gegen vertrauenswürdige API-Endpunkte beschränkt.

Sie wiederholt POST-, PUT-, PATCH- oder DELETE-Operationen nicht automatisch, da diese zusätzliche Sicherheiten erfordern.

Sie gibt nicht-wiederholbare HTTP-Antworten an den Aufrufer zurück, die entscheiden müssen, wie sie damit umgehen.

Für Produktionssysteme sollten Sie additionally Antworttypen validieren, Antwortgrößenlimits durchsetzen und wiederholbare Transport-Fehler von permanenten TLS- oder Konfigurationsfehlern unterscheiden.

6. Warum das erneute Senden von POST-Anforderungen gefährlich sein kann

Stellen Sie sich eine E-Commerce-Anwendung vor, die diese Anforderung sendet:

POST /api/orders
Content-Type: application/json

{
  "product_id": 42,
  "quantity": 1
}

Der Fernservice erstellt die Bestellung, aber die Verbindung bricht ab, bevor Ihre Anwendung die Antwort erhält.

Ihre Anwendung sieht einen Timeout.

Ist die Bestellung fehlgeschlagen?

Nicht notwendigerweise. Die Bestellung existiert vielleicht bereits.

Wenn Ihre Anwendung sofort wiederholt, könnte sie eine zweite Bestellung erstellen.

Das ist deshalb, weil ein Timeout nicht beweist, dass eine Operation auf dem Server fehlgeschlagen ist.

Idempotenz-Schlüssel verwenden, wenn unterstützt

Einige APIs unterstützen Idempotenz-Schlüssel.

Zum Beispiel:

Idempotency-Key: order-8f7a2c

Wenn die API einen dokumentierten Idempotenz-Mechanismus bereitstellt, kann das Wiederverwenden des gleichen Schlüssels für Wiederholungen derselben logischen Operation doppelte Verarbeitung verhindern.

Dieses Verhalten ist API-spezifisch. Das Hinzufügen eines Idempotency-Key-Headers macht eine beliebige API nicht automatisch idempotent.

Für Operationen im Zusammenhang mit Zahlungen, Bestellungen, Abonnements oder Datenbankmodifikationen sollten Sie die offizielle Dokumentation des Anbieters zu Retries und Idempotenz befolgen.

Existiert kein Idempotenz-Mechanismus, müssen Sie möglicherweise den Status der Operation abfragen oder Ergebnisse reconciliate, bevor Sie es erneut versuchen.

7. Schlafenszeiten in lang laufenden Web-Anforderungen vermeiden

Technical workflow illustration

Unser Beispiel verwendet usleep(), um das Wiederholungsverhalten leicht verständlich zu machen.

Das kann für kurze Operationen mit einem eng gesteuerten Wiederholungsbudget akzeptabel sein.

Eine Produktionswebsite sollte PHP-Worker jedoch nicht für Minuten beschäftigen, während auf eine externe API gewartet wird.

Stellen Sie sich vor, eine API gibt zurück:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

Eine Stunde Wartezeit innerhalb einer HTTP-Anfrage wäre ein schlechtes Design.

Eine bessere Lösung ist, die Operation zu verzögern.

Beispielsweise einen pending Job speichern:

Job ID: 1842
Status: pending
Attempts: 2
Next attempt: 2026-11-20 14:30:00 UTC

Ein geplanter Worker kann die Arbeit dann verarbeiten, wenn sie fällig wird.

Dieser Ansatz ist besonders nützlich für:

  • Produktkatalog-Synchronisierung.
  • E-Mail-Zustellung.
  • Social-Media-Publikation.
  • Dokumentverarbeitung.
  • Inventur-Updates.
  • Große API-Importe.

Es macht Fehler auch leichter zu überwachen und wiederherzustellen.

8. Wiederholungsinformationen in einer Datenbank speichern

Für eine MariaDB-basierte Anwendung könnte eine einfache Job-Tabelle so aussehen:

CREATE TABLE api_jobs (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    job_type VARCHAR(100) NOT NULL,
    payload_json LONGTEXT NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    attempts INT UNSIGNED NOT NULL DEFAULT 0,
    next_attempt_at DATETIME NOT NULL,
    last_error TEXT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    INDEX idx_jobs_ready (
        status,
        next_attempt_at
    )
);

Der Worker wählt Jobs aus, wo:

SELECT id, job_type, payload_json
FROM api_jobs
WHERE status = 'pending'
AND next_attempt_at <= UTC_TIMESTAMP()
ORDER BY next_attempt_at, id
LIMIT 20;

Dies ist nur derAuswahlteil einer Queue-Implementation.

Wenn mehrere Worker gleichzeitig laufen können, müssen Jobs atomar beansprucht werden, unter Verwendung einer geeigneten Transaktions- und Sperrstrategie, um doppelte Verarbeitung zu verhindern.

Der Worker sollte außerdem eine maximale Wiederholungsanzahl anwenden und dauerhaft fehlschlagende Jobs in einen Zustand überführen, der Untersuchung erfordert.

Für kleine Anwendungen kann dieser datenbankbasierte Ansatz ausreichen, ohne Redis oder einen dedizierten Nachrichtenbroker einzuführen.

9. Fehlerprotokollieren ohne sensible Daten

Ein nützliches API-Protokoll sollte vier Fragen beantworten:

  1. Welche Operation ist fehlgeschlagen?
  2. Welcher Fernservice war beteiligt?
  3. Welcher HTTP-Status oder Transport-Fehler?
  4. Wann wiederholt die Anwendung?

Zum Beispiel:

[2026-11-20 13:25:00 UTC]
service=inventory-api
operation=sync-products
status=429
attempt=2
next_retry=2026-11-20T13:26:00Z

Vermeiden Sie das Protokollieren von API-Schlüsseln, Trägertoken, vollständigen Autorisierungsheadern, Passwörtern oder unnötigen persönlichen Informationen.

Wenn Sie Anfragen korrelieren müssen, verwenden Sie eine generierte Anfrage-Identifikator.

Zum Beispiel:

$requestId = bin2hex(random_bytes(8));

Sie können diese Identifikator in Anwendungsprotokollen einschließen und, wenn unterstützt, an den Fernservice senden.

10. Ihre Wiederholungsstrategie vor der Produktion testen

Eine Wiederholungsmechanismus sollte gegen vorhersehbare Fehler-Szenarien getestet werden.

Sie müssen nicht auf einen echten API-Ausfall warten.

Ein lokales Test-Endpunkt kann absichtlich bestimmte Statuscodes zurückgeben.

Zum Beispiel:

<?php
declare(strict_types=1);

header('Content-Type: application/json');

http_response_code(429);
header('Retry-After: 3');

echo json_encode([
    'error' => 'rate_limit_exceeded',
]);

Führen Sie dieses Endpunkt nur in einer lokalen oder geschützten Testumgebung aus.

Dann überprüfen Sie, dass Ihr Client:

  • Erkennt HTTP 429.
  • Lest den Retry-After-Header.
  • Wartet vor dem Wiederholen.
  • Hört nach der konfigurierten Anzahl von Versuchen auf.
  • Protokolliert den Fehler ohne Exposition von Geheimnissen.

Wiederholen Sie mit HTTP 503 und einem absichtlich langsamen Endpunkt.

Testen Sie auch eine HTTP 400-Antwort, um zu bestätigen, dass der Client keine permanenten Anfrage-Fehler wiederholt.

Testen Sie schließlich eine Operation, die möglicherweise erfolgreich war, bevor die Verbindung fehlgeschlagen ist. Dies ist essenziell für Zahlungs- und Bestellungsintegrationen.

11. Produktions-Checkliste für zuverlässige API-Integrationen

Bevor Sie eine API-Integration deployen, überprüfen Sie Folgendes:

Check Expected behavior
Connection timeout Defined and tested
Overall timeout Defined and tested
HTTP 429 Respects rate limits
HTTP 5xx Retries selectively
HTTP 4xx No blind retries
Retry limit Prevents endless loops
Retry delay Backoff with jitter
POST operations Idempotency or reconciliation
Long waiting periods Deferred to a worker
Logs Useful, private, sanitized
Worker concurrency Duplicate execution prevented
Permanent failures Visible and recoverable

Fazit: zuverlässige APIs erfordern kontrolliertes Fehlerhandhaben

Externe APIs sind nie perfekt verfügbar. Selbst ein gut gewarteter Dienst kann vorübergehende Überlastung, Netzwerkunterbrechungen oder Rate-Limiting erleben.

Das Ziel ist nicht, jeden Fehler auszuschalten. Es geht, Ihre Anwendung vorhersehbar auf Fehler reagieren zu lassen.

Beginnen Sie mit sinnvollen Timeouts und expliziten HTTP-Fehlerbehandlung. Fügen Sie begrenzte Retries mit exponentiellem Backoff hinzu, respektieren Sie server-bereitgestellte Wiederholungsverzögerungen, und vermeiden Sie automatisch wiederholte Operationen, die doppelte Daten erzeugen könnten.

Bei komplexeren Integrationen sollten Sie Retries in einen persistenten Job-Queue verschieben, anstatt Web-Anfragen offen zu halten.

Diese Prinzipien gelten für fast jede moderne PHP-Anwendung, egal ob Sie eine CMS-Erweiterung bauen, einen E-Commerce-Katalog synchronisieren, transaktionalen E-Mails senden oder einen Zahlungsdienst integrieren.

Ein zuverlässiger API-Client ist einer, der nicht nur weiß, wie man eine Anforderung sendet, sondern auch wann man wiederholt, wann man wartet und wann man aufhört.

Offizielle Referenzen

Illustration of the article's main concept