Web & Udvikling

Sådan håndterer du API-tidsudløb, hastighedsgrænser og genforsøg i PHP

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

Lær, hvordan du opbygger pålidelige PHP API-integrationer med forbindelsestidsudløb, HTTP-fejlbehandling, eksponentiel tilbageholdenhed, Retry-After-understøttelse og sikre genforsøgsstrategier.

Sådan håndteres API-timeouts, rate limits og retries i PHP

En API-integration fungerer perfekt under udvikling. Så en dag stopper din planlagte opgave halvvejs. En ekstern tjeneste svarer med HTTP 429, en forbindelse får timeout, eller en HTTP 503-fejl afbryder en synkronisering.

Fristelsen er at prøve anmodningen igen med det samme.

Men at prøve igen uden en strategi kan gøre problemet værre. Det kan overbelaste en API, der allerede kæmper, overskride rate limits eller ved et uheld oprette dubletter af ordrer og betalinger.

En pålidelig API-klient kræver mere end et vellykket curl_exec()-kald.

I denne vejledning bygger vi en praktisk PHP HTTP-klient, der håndterer forbindelses-timeouts, HTTP-fejl, rate limits og midlertidige fejl. Vi forklarer også, hvornår det er sikkert at prøve igen, hvornår det ikke er, og hvordan man diagnosticerer problemer i produktion.

Eksemplerne bruger PHP's indbyggede cURL-udvidelse uden Composer eller tredjepartsafhængigheder.

1. Forstå de forskellige typer API-fejl

Ikke hver mislykket anmodning bør håndteres på samme måde.

Fejl Typisk årsag Anbefalet handling
Forbindelses-timeout Server utilgængelig eller langsom forbindelse Prøv igen med forsigtighed
HTTP 400 Ugyldige anmodningsparametre Ret anmodningen
HTTP 401 Ugyldige eller udløbne legitimationsoplysninger Kontrollér godkendelsen
HTTP 404 Ressource ikke fundet Kontrollér ressource-id'et
HTTP 429 API-rate limit overskredet Respektér Retry-After
HTTP 500 Intern serverfejl Prøv igen selektivt
HTTP 503 Midlertidig tjenesteutilgængelighed Prøv igen med forsinkelse
Ugyldig JSON Uventet svarformat Log og undersøg

En netværksfejl er også forskellig fra en HTTP-fejl.

Når en API returnerer HTTP 500, blev HTTP-anmodningen gennemført, og serveren returnerede et fejlsvar.

Når cURL rapporterer en forbindelsesfejl, har din applikation muligvis slet ikke modtaget noget HTTP-svar.

Den forskel betyder noget, når man beslutter, om man skal prøve igen.

2. Konfigurér altid forbindelses- og anmodningstimeouts

PHP cURL tilbyder to særligt nyttige indstillinger:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT begrænser forbindelsesfasen, mens CURLOPT_TIMEOUT begrænser den samlede overførselsvarighed. Begge er dokumenteret i PHP's officielle cURL-reference.

Uden passende grænser kan en langsom ekstern tjeneste besætte PHP-workere i meget længere tid end forventet.

Et praktisk udgangspunkt for en konventionel JSON-API kan være fem sekunder til etablering af forbindelsen og femten sekunder til den komplette anmodning.

Det er ikke universelle værdier. En filupload eller generering af en langvarig rapport kan kræve en anden timeout-politik.

Lav din første API-anmodning

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

Dette etablerer et nyttigt fundament, men det håndterer endnu ikke rate limits eller fejl, der kan prøves igen.

3. Forstå HTTP 429 og Retry-After

HTTP 429 betyder, at klienten har sendt for mange anmodninger inden for en periode defineret af API-udbyderen.

Nogle API'er pålægger grænser pr. minut, pr. time, pr. API-nøgle eller pr. konto.

En server kan svare med:

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

Retry-After-headeren fortæller klienten, hvor længe den bør vente, før den prøver igen.

Headeren kan indeholde enten et antal sekunder eller en HTTP-dato.

For eksempel:

Retry-After: 120

Eller:

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

En velopdraget klient bør respektere denne instruks i stedet for gentagne gange at sende anmodninger.

Hvis serveren ikke angiver en forsinkelse før næste forsøg, skal din applikation have en reserve­strategi.

4. Brug eksponentiel backoff i stedet for øjeblikkelige gentagne forsøg

Eksponentiel backoff øger ventetiden efter successive fejl.

For eksempel:

Gentaget forsøg Eksempel på forsinkelse
1 1 sekund
2 2 sekunder
3 4 sekunder
4 8 sekunder

I stedet for at prøve igen hvert sekund venter applikationen gradvist længere.

At tilføje en lille tilfældig variation, kaldet jitter, hjælper med at forhindre, at mange klienter prøver igen samtidig.

Her er en genanvendelig forsinkelsesfunktion:

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

Dette bruger fuld jitter: den faktiske forsinkelse vælges tilfældigt mellem nul og den eksponentielle grænse.

Den tilfældige forsinkelse reducerer synkroniserede gentagne forsøgsbølger, selvom den ikke erstatter en eksplicit serverangivet Retry-After-instruks.

Illustration of the article's main concept

5. Byg en genanvendelig PHP API-klient

Lad os kombinere de foregående koncepter i en fungerende implementering.

Vores klient vil:

  • Sætte forbindelses- og samlede anmodningstimeouts.
  • Returnere HTTP-status og svarkroppen.
  • Registrere overførselsfejl.
  • Prøve udvalgte midlertidige fejl igen.
  • Respektere Retry-After, når den er til stede.
  • Begrænse antallet af forsøg.
  • Undgå automatisk at prøve ikke-idempotente handlinger igen.
<?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.'
    );
}

Sådan bruger du den

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

Denne implementering er bevidst begrænset til GET-anmodninger mod betroede API-endepunkter.

Den prøver ikke automatisk POST-, PUT-, PATCH- eller DELETE-handlinger igen, fordi disse kræver yderligere sikkerhedsforanstaltninger.

Den returnerer også ikke-genstartbare HTTP-svar til kalderen, som selv skal beslutte, hvordan de skal håndteres.

For produktionssystemer bør du desuden validere svartyper, håndhæve grænser for svarsstørrelse og skelne mellem genstartbare overførselsfejl og permanente TLS- eller konfigurationsfejl.

6. Hvorfor det kan være farligt at prøve POST-anmodninger igen

Forestil dig en e-handelsapplikation, der sender denne anmodning:

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

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

Den eksterne API opretter ordren, men forbindelsen afbrydes, før din applikation modtager svaret.

Din applikation ser et timeout.

Mislykkedes ordren?

Ikke nødvendigvis. Ordren findes muligvis allerede.

Hvis din applikation straks prøver igen, kan den oprette en anden ordre.

Det er derfor, at et timeout ikke beviser, at en handling mislykkedes på serveren.

Brug idempotensnøgler, når de understøttes

Nogle API'er understøtter idempotensnøgler.

For eksempel:

Idempotency-Key: order-8f7a2c

Når API'et tilbyder en dokumenteret idempotensmekanisme, kan genbrug af den samme nøgle for gentagne forsøg af den samme logiske handling forhindre dubletbehandling.

Men denne adfærd er API-specifik. At tilføje en Idempotency-Key-header gør ikke automatisk et vilkårligt API idempotent.

For handlinger, der involverer betalinger, ordrer, abonnementer eller databasemodifikationer, følg udbyderens officielle dokumentation for gentagne forsøg og idempotens.

Når der ikke findes nogen idempotensmekanisme, kan det være nødvendigt at forespørge på handlingens status eller afstemme resultaterne, før du forsøger igen.

7. Undgå at sove inde i langvarige webanmodninger

Technical workflow illustration

Vores eksempel bruger usleep() for at gøre gentagelsesadfærden nem at forstå.

Det kan være acceptabelt for korte handlinger med et stramt kontrolleret gentagelsesbudget.

Men en produktionsweb­side bør ikke holde PHP-workere optaget i minutter, mens den venter på en ekstern API.

Forestil dig, at en API svarer med:

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

At vente i en time inde i en HTTP-anmodning ville være en dårlig løsning.

En bedre løsning er at udskyde handlingen.

Eksempelvis kan du gemme et ventende job:

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

En planlagt worker kan derefter behandle jobbet, når det bliver berettiget.

Denne tilgang er især nyttig til:

  • Synkronisering af produktkataloger.
  • Levering af e-mails.
  • Publicering på sociale medier.
  • Dokumentbehandling.
  • Lageropdateringer.
  • Store API-importer.

Den gør det også lettere at overvåge og gendanne fejl.

8. Gem gentagelsesinformation i en database

For en MariaDB-baseret applikation kunne en simpel jobtabel se sådan ud:

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

Workeren vælger jobs, hvor:

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;

Dette er kun udvægelsesdelen af en køimplementering.

Hvis flere workere kan køre samtidig, skal jobs gøres krav på atomisk ved hjælp af en passende transaktions- og låsestrategi for at forhindre dubletbehandling.

Workeren bør også anvende et maksimalt antal gentagne forsøg og flytte job, der permanent mislykkes, over i en tilstand, der kræver undersøgelse.

For en lille applikation kan denne databasebaserede tilgang være tilstrækkelig uden at indføre Redis eller en dedikeret meddelelses­mægler.

9. Log fejl uden at afsløre følsomme data

En nyttig API-log bør besvare fire spørgsmål:

  1. Hvilken handling mislykkedes?
  2. Hvilken ekstern tjeneste var involveret?
  3. Hvad var HTTP-status eller overførselsfejlen?
  4. Hvornår vil applikationen prøve igen?

For eksempel:

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

Undgå at logge API-nøgler, bearer-tokens, fuldstændige godkendelsesheadere, adgangskoder eller unødvendige personlige oplysninger.

Hvis du skal korrelere anmodninger, skal du bruge et genereret anmodnings-id.

For eksempel:

$requestId = bin2hex(random_bytes(8));

Du kan inkludere dette id i applikationsloggene og, når det understøttes, sende det til den eksterne API.

10. Test din gentagelsesstrategi før produktion

En gentagelsesmekanisme bør testes mod forudsigelige fejlscenarier.

Du behøver ikke vente på et rigtigt API-nedbrud.

Et lokalt testendepunkt kan med vilje returnere specifikke statuskoder.

For eksempel:

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

Kør kun dette endepunkt i et lokalt eller beskyttet testmiljø.

Kontrollér derefter, at din klient:

  • Registrerer HTTP 429.
  • Læser Retry-After-headeren.
  • Venter, før den prøver igen.
  • Stopper efter det konfigurerede antal forsøg.
  • Registrerer fejlen uden at afsløre hemmeligheder.

Gentag med HTTP 503 og et med vilje langsomt endepunkt.

Test også et HTTP 400-svar for at bekræfte, at klienten ikke prøver permanente anmodningsfejl igen.

Test til sidst en handling, der kan være lykkedes, før forbindelsen fejlede. Dette er afgørende for betalings- og ordreintegrationer.

11. En produktionscheckliste for pålidelige API-integrationer

Før du implementerer en API-integration, skal du kontrollere følgende:

Kontrol Forventet adfærd
Forbindelses-timeout Defineret og testet
Samlet timeout Defineret og testet
HTTP 429 Respekterer rate limits
HTTP 5xx Prøver igen selektivt
HTTP 4xx Ingen blinde gentagne forsøg
Grænse for gentagne forsøg Forhindrer endeløse løkker
Forsinkelse ved gentagne forsøg Backoff med jitter
POST-handlinger Idempotens eller afstemning
Lange ventetider Udskudt til en worker
Logge Nyttige, private, saniterede
Worker-konkurrence Dubletkørsel forhindret
Permanente fejl Synlige og gendannelige

Konklusion: pålidelige API'er kræver kontrolleret fejlhåndtering

Eksterne API'er er aldrig perfekt tilgængelige.

Selv en velvedligeholdt tjeneste kan opleve midlertidig overbelastning, netværksafbrydelser eller rate limiting.

Målet er ikke at eliminere hver fejl. Det er at få din applikation til at reagere forudsigeligt, når fejl opstår.

Start med fornuftige timeouts og eksplicit HTTP-fejlhåndtering. Tilføj afgrænsede gentagne forsøg med eksponentiel backoff, respektér serverangivne forsinkelser før næste forsøg, og undgå automatisk at gentage handlinger, der kunne skabe dublerede data.

For mere komplekse integrationer bør du flytte gentagne forsøg over i en vedvarende jobkø i stedet for at holde webanmodninger åbne.

Disse principper gælder for næsten enhver moderne PHP-applikation, uanset om du bygger en CMS-udvidelse, synkroniserer et e-handelskatalog, sender transaktionelle e-mails eller integrerer en betalingstjeneste.

En pålidelig API-klient er en, der ikke kun ved, hvordan man sender en anmodning, men også hvornår man skal prøve igen, hvornår man skal vente, og hvornår man skal stoppe.

Officielle referencer