Web & Ontwikkeling

Hoe om te gaan met API Timeouts, Rate Limits en Retries in PHP

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

Leer hoe je betrouwbare PHP API-integraties kunt bouwen met verbindingstimeouts, HTTP-foutafhandeling, exponentiële backoff, Retry-After-ondersteuning en veilige retrystrategieën.

Hoe om te gaan met API-timeouts, rate limits en retries in PHP

Een API-integratie werkt perfect tijdens de ontwikkeling. Op een dag stopt je geplande taak halverwege. Een externe service reageert met HTTP 429, een time-out van de verbinding, of een HTTP 503-fout onderbreekt een synchronisatie.

De verleiding is om de aanvraag onmiddellijk opnieuw te proberen.

Maar opnieuw proberen zonder strategie kan het probleem erger maken. Het kan een reeds worstelende API overbelasten, rate limits overschrijden, of per ongeluk dubbele bestellingen en betalingen maken.

Een betrouwbare API-client heeft meer nodig dan een succesvolle curl_exec()-aanroep.

In deze tutorial bouwen we een praktische PHP HTTP-client die verbindings-timeouts, HTTP-fouten, rate limits en tijdelijke fouten afhandelt. We leggen ook uit wanneer opnieuw proberen veilig is, wanneer niet, en hoe problemen in productie te diagnosticeren.

De voorbeelden gebruiken PHP's ingebouwde cURL-extensie, zonder Composer of afhankelijkheden van derden.

1. Begrijp de verschillende typen API-fouten

Niet elke mislukte aanvraag moet op dezelfde manier worden afgehandeld.

Fout Typische oorzaak Aanbevolen actie
Verbinding time-out Server onbereikbare of langzame verbinding Voorzichtig opnieuw proberen
HTTP 400 Ongeldige aanvraagparameters De aanvraag corrigeren
HTTP 401 Ongeldige of verlopen referenties Authenticatie controleren
HTTP 404 Resource niet gevonden Resource-identifier controleren
HTTP 429 API-rate-limit overschreden Retry-After respecteren
HTTP 500 Interne serverfout Selectief opnieuw proberen
HTTP 503 Tijdelijke service-onbeschikbaarheid Met vertraging opnieuw proberen
Ongeldige JSON Onverwacht response-formaat Logen en onderzoeken

Een netwerkfout is ook anders dan een HTTP-fout.

Wanneer een API HTTP 500 returned, is de HTTP-aanvraag voltooid en de server heeft een foutresponse geretourneerd.

Wanneer cURL een verbindingsfout meldt, heeft je applicatie misschien helemaal geen HTTP-response ontvangen.

Dat verschil is van belang bij de beslissing of opnieuw geprobeerd moet worden.

2. Configureer altijd verbindings- en aanvraag-timeouts

PHP cURL twee bijzonder nuttige instellingen:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT beperkt de verbindingsfase, terwijl CURLOPT_TIMEOUT de totale overdrachtsduur beperkt. Beide zijn gedocumenteerd in de officiële cURL-referentie van PHP.

Zonder geschikte limieten kan een langzame externe service PHP-werkers veel langer bezet houden dan verwacht.

Een praktisch startpunt voor een conventionele JSON-API zou vijf seconden kunnen zijn voor het tot stand brengen van de verbinding en vijftien seconden voor de volledige aanvraag.

Dit zijn geen universele waarden. Een bestandsupload of een langlopende rapportgeneratie heeft wellicht een ander time-outbeleid nodig.

Maak je eerste API-aanvraag

<?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;

Dit legt een nuttige basis, maar het afhandelt nog geen rate limits of herhaalbare fouten.

3. Begrijp HTTP 429 en Retry-After

HTTP 429 betekent dat de client te veel aanvragen heeft verzonden binnen een periode die is gedefinieerd door de API-provider.

Sommige APIs leggen limieten op per minuut, per hour, per API-sleutel of per account.

Een server kan reageren met:

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

De Retry-After-header vertelt de client hoe lang hij moet wachten voordat hij het opnieuw probeert.

De header kan zowel een aantal seconden als een HTTP-datum bevatten.

Voorbeeld:

Retry-After: 120

Of:

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

Een goed gedragde client deze instructie moet respecteren in plaats van herhaaldelijk aanvragen te verzenden.

Als de server geen retry-vertraging verstrekt, heeft je applicatie een fallback-strategie nodig.

4. Gebruik exponentiële backoff in plaats van onmiddellijk opnieuw proberen

Exponentiële backoff verhoogt de wachttijd na opeenvolgende fouten.

Voorbeeld:

Retry Voorbeeldvertraging
1 1 seconde
2 2 seconden
3 4 seconden
4 8 seconden

In plaats van elke seconde opnieuw te proberen, wacht de applicatie Progressief langer.

Het toevoegen van een kleine willekeurige variatie, genaamd jitter, helpt te voorkomen dat veel clients tegelijkertijd opnieuw proberen.

Hier is een herbruikbare delay-functie:

<?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
    );
}

Dit gebruikt full jitter: de daadwerkelijke vertraging wordt willekeurig geselecteerd tussen nul en de exponentiële cap.

De willekeurige vertraging vermindert gesynchroniseerde retry-bursts, hoewel het een expliciete server-geleverde Retry-After-instructie niet vervangt.

Illustration of the article's main concept

5. Bouw een herbruikbare PHP API-client

Laten we de vorige concepten combineren in een werkende implementatie.

Onze client zal:

  • Verbindings- en totale aanvraag-timeouts instellen.
  • HTTP-status en response-body retourneren.
  • Transportfouten detecteren.
  • Geselecteerde tijdelijke fouten opnieuw proberen.
  • Retry-After respecteren wanneer aanwezig.
  • Het aantal pogingen beperken.
  • Automatisch opnieuw proberen van niet-idempotente operaties vermijden.
<?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.'
    );
}

Hoe te gebruiken

<?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());
}

Deze implementatie is opzettelijk beperkt tot GET-aanvragen naar vertrouwde API-eindpunten.

Het retryd automatisch geen POST-, PUT-, PATCH- of DELETE-operaties, omdat deze aanvullende waarborgen vereisen.

Het retourneert ook niet-herhaalbare HTTP-responses aan de aanroeper, die moet beslissen hoe deze af te handelen.

Voor productiesystemen moet je bovendien response-typen valideren, response-grootte-limits opleggen en onderscheid maken tussen herhaalbare transportfouten en permanente TLS- of configuratiefouten.

6. Waarom opnieuw proberen van POST-aanvragen gevaarlijk kan zijn

Stel je voor dat een e-commerce-applicatie deze aanvraag verzendt:

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

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

De externe API creëert de bestelling, maar de verbinding valt voordat je applicatie de response ontvangt.

Je applicatie ziet een time-out.

Mislukte de bestelling?

Dat is niet noodzakelijk. De bestelling kan al bestaan.

Als je applicatie onmiddellijk opnieuw probeert, kan het een tweede bestelling creëren.

Daarom bewijst een time-out niet dat een operatie is mislukken op de server.

Gebruik idempotentie-sleutels wanneer ondersteund

Sommige APIs ondersteunen idempotentie-sleutels.

Voorbeeld:

Idempotency-Key: order-8f7a2c

Wanneer een API een gedocumenteerd idempotentie-mecanisme verstrekt, het hergebruiken van dezelfde sleutel voor retries van dezelfde logische operatie kan dubbele verwerking voorkomen.

Maar dit gedrag is API-specifiek. Het toevoegen van een Idempotency-Key-header maakt een willekeurige API automatisch idempotent.

Voor operaties die betalingen, bestellingen, abonnementen of databasewijzigingen omvatten, volg de officiële retry- en idempotentie-documentatie van de provider.

Wanneer geen idempotentie-mecanisme bestaat, moet je misschien de status van de operatie opvragen of resultaten afstemmen voordat je het opnieuw probeert.

7. Vermijd slapen binnen langlopende web-aanvragen

Technical workflow illustration

Ons voorbeeld gebruikt usleep() om het retry-gedrag gemakkelijk te begrijpen.

Dat kan acceptabel zijn voor korte operaties met een strikt beheerd retry-budget.

Een productiewebsite echter mag PHP-werkers niet minutenlang bezet houden terwijl hij wacht op een externe API.

Stel dat een API reageert met:

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

Een uur wachten binnen een HTTP-aanvraag zou een slecht ontwerp zijn.

Een betere oplossing is om de operatie uit te stellen.

Voorbeeld, bewaar een openstaande taak:

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

Een geplande worker kan de taak dan verwerken wanneer deze geschikt wordt.

Deze benadering is vooral nuttig voor:

  • Productcatalogussynchronisatie.
  • E-mailbezorging.
  • Social media publicatie.
  • Documentverwerking.
  • Voorraadupdates.
  • Grote API-import.

Het maakt ook fouten eenvarder te monitoren en te herstellen.

8. Bewaar retry-informatie in een database

Voor een MariaDB-ondersteunde applicatie, een eenvoudige taaltabel zou er zo kunnen uitzien:

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
    )
);

De worker selecteert taken waar:

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;

Dit is alleen het selectiegedeelte van een queue-implementatie.

Als meerdere workers tegelijkertijd kunnen lopen, moet taken atomisch worden geclaimd, met behulp van een geschikte transactie en locking-strategie, om dubbele verwerking te voorkomen.

De worker moet ook een maximum retry-telling toepassen en permanent mislukte taken verplaatsen naar een status die onderzoek vereist.

Voor een kleine applicatie kan deze database-ondersteunde benadering voldoende zijn zonder Redis of een aparte message broker in te voeren.

9. Log fouten without het blootstellen van gevoelige gegevens

Een nuttige API-log moet vier vragen beantwoorden:

  1. Welke operatie is mislukt?
  2. Welke externe service was betrokken?
  3. Wat was de HTTP-status of transportfout?
  4. Wanneer zal de applicatie opnieuw proberen?

Voorbeeld:

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

Vermijd het loggen van API-sleutels, bearer tokens, volledige autorisatie-headers, wachtwoorden of onnodige persoonlijke gegevens.

Als je aanvragen moet koppelen, gebruik een gegenereerde aanvraag-identifier.

Voorbeeld:

$requestId = bin2hex(random_bytes(8));

Deze identifier kan je opnemen in applicatie-logs en, indien ondersteund, verzenden naar de externe API.

10. Test je retry-strategie voordat je in productie gaat

Een retry-mecanisme moet worden getest against voorspelbare foutscenario's.

Je hoeft niet te wachten op een echte API-storing.

Een lokaal test-eindpunt kan opzettelijk specifieke statuscodes retourneren.

Voorbeeld:

<?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',
]);

Voer dit eindpunt uit alleen in een lokaal of beveiligd testomgeving.

Verificeer dan dat je client:

  • HTTP 429 detecteert.
  • De Retry-After header leest.
  • Wacht voordat het opnieuw probeert.
  • Stopt na het geconfigureerde aantal pogingen.
  • Neemt de fout op without het blootstellen van geheimen.

Herhaal met HTTP 503 en een opzettelijk langzaam eindpunt.

Test ook een HTTP 400-response om te bevestigen dat de client permanente aanvraagfouten niet opnieuw probeert.

Ten slotte, test een operatie die misschien is geslaagd voordat de verbinding viel. Dit is essentieel voor betalings- en integraties.

11. Een productiechecklist voor betrouwbare API-integraties

Voordat je een API-integratie implementeert, verificeer het volgende:

Controle Verwacht gedrag
Verbinding time-out Gedefinieerd en getest
Totale time-out Gedefinieerd en getest
HTTP 429 Respecteert rate limits
HTTP 5xx Selectief opnieuw proberen
HTTP 4xx Geen blind retries
Retry-limiet Voorkomt eindeloze lussen
Retry-vertraging Backoff met jitter
POST-operaties Idempotentie of afstemming
Lange wachttijden Uitgesteld naar een worker
Logs Nuttig, privaat, gesanitiseerd
Worker-concurrentie Dubbele uitvoering voorkomen
Permanente fouten Zichtbaar en herstelbaar

Conclusie: betrouwbare API's vereisen gecontroleerde foutafhandeling

Externe API's zijn nooit perfect beschikbaar.

Zelfs een goed onderhouden service kan tijdelijke overbelasting, netwerkonderbrekingen of rate limiting ervaren.

Het doel is niet om elke fout te elimineren. Het is om je applicatie te latet reageren op een voorspelbare manier wanneer fouten gebeuren.

Begin met redelijke time-outs en expliciete HTTP-foutafhandeling. Voeg beperkte retries toe met exponentiële backoff, respecteer server-geleverde retry-vertragingen en vermijd automatisch het herhalen van operaties die dubbele gegevens kunnen creëren.

Voor complexere integraties, verplaats retries naar een persistente job-queue in plaats van web-aanvragen open te houden.

Deze principes zijn van toepassing op bijna elke moderne PHP-applicatie, of je nu een CMS-extensie bouwt, een e-commerce-catalogus synchroniseert, transactionele e-mails verzendt of een betalingsservice integreert.

Een betrouwbare API-client is iemand die niet only weet hoe een aanvraag te verzenden, maar ook wanneer opnieuw te proberen, wanneer te wachten en wanneer te stoppen.

Officiële referenties