Nett og utvikling

Slik håndterer du API-tidsavbrudd, ratebegrensninger og gjentakelser i PHP

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

Lær hvordan du bygger pålitelige PHP API-integrasjoner med tilkoblingstidsavbrudd, HTTP-feilhåndtering, eksponentiell tilbakegang, Retry-After-støtte og sikre gjentakelsesstrategier.

Slik håndterer du API-tidsavbrudd, hastighetsgrenser og nye forsøk i PHP

En API-integrasjon fungerer perfekt under utvikling. Så en dag stopper den planlagte oppgaven din halvveis. En ekstern tjeneste svarer med HTTP 429, en tilkobling tømer ut for tidsfristen, eller en HTTP 503-feil avbryter en synkronisering.

Fristelsen er å prøve forespørselen på nytt umiddelbart.

Men å prøve på nytt uten en strategi kan gjøre problemet verre. Det kan overbelaste en API som allerede sliter, overskride hastighetsgrensene, eller ved et uhell opprette dupliserte ordrer og betalinger.

En pålitelig API-klient trenger mer enn et vellykket curl_exec()-kall.

I denne veiledningen skal vi bygge en praktisk PHP HTTP-klient som håndterer tilkoblingsavbrudd, HTTP-feil, hastighetsgrenser og midlertidige feil. Vi skal også forklare når det er trygt å prøve på nytt, når det ikke er det, og hvordan du diagnostiserer problemer i produksjon.

Eksemplene bruker PHas' innebygde cURL-utvidelse, uten Composer eller tredjepartsavhengigheter.

1. Forstå de ulike typene API-feil

Ikke hver mislykkede forespørsel bør håndteres på samme måte.

Feil Typisk årsak Anbefalt handling
Tidsavbrudd for tilkobling Server utilgjengelig eller treg tilkobling Prøv på nytt med forsiktighet
HTTP 400 Ugyldige forespørselsparametere Fiks forespørselen
HTTP 401 Ugyldige eller utløpte legitimasjonspapirer Sjekk autentisering
HTTP 404 Ressursen finnes ikke Sjekk ressursidentifikatoren
HTTP 429 API-hastighetsgrense overskredet Respekter Retry-After
HTTP 500 Intern serverfeil Prøv på nytt selektivt
HTTP 503 Midlertidig utilgjengelighet av tjenesten Prøv på nytt med forsinkelse
Ugyldig JSON Uventet responsformat Logg og undersøk

En nettverksfeil er også forskjellig fra en HTTP-feil.

Når en API returnerer HTTP 500, fullførte HTTP-forespørselen og serveren returnerte et feilsvar.

Når cURL rapporterer en tilkoblingsfeil, kan det hende at applikasjonen din ikke mottok noe HTTP-svar i det hele tatt.

Den forskjellen betyr noe når du bestemmer om du skal prøve på nytt.

2. Konfigurer alltid tidsavbrudd for tilkobling og forespørsel

PHP cURL gir to spesielt nyttige innstillinger:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT begrenser tilkoblingsfasen, mens CURLOPT_TIMEOUT begrenser den samlede overføringsvarigheten. Begge er dokumentert i PHas' offisielle cURL-referanse.

Uten passende grenser kan en treg ekstern tjeneste oppta PHP-arbeidere mye lenger enn forventet.

Et praktisk utgangspunkt for en konvensjonell JSON-API kan være fem sekunder for å etablere tilkoblingen og femten sekunder for hele forespørselen.

Dette er ikke universelle verdier. En filopplasting eller generering av en langvarig rapport kan trenge en annen tidsavbruddpolitikk.

Gjør din første API-forespørsel

<?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 nyttig fundament, men det håndterer ennå ikke hastighetsgrenser eller feil som kan prøves på nytt.

3. Forstå HTTP 429 og Retry-After

HTTP 429 betyr at klienten har sendt for mange forespørsler innenfor en periode definert av API-leverandøren.

Noen API-er pålegger grenser per minutt, per time, per API-nøkkel eller per konto.

En server kan svare med:

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

Retry-After-hodefeltet forteller klienten hvor lenge den bør vente før den prøver igjen.

Hodefeltet kan inneholde enten et antall sekunder eller en HTTP-dato.

For eksempel:

Retry-After: 120

Eller:

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

En veloppdratt klient bør respektere denne instruksjonen i stedet for gjentatte ganger å sende forespørsler.

Hvis serveren ikke gir en forsinkelse for nytt forsøk, trenger applikasjonen din en reserve­strategi.

4. Bruk eksponentiell tilbakegang i stedet for umiddelbare nye forsøk

Eksponentiell tilbakegang øker ventetiden etter suksessive feil.

For eksempel:

Nytt forsøk Eksempel på forsinkelse
1 1 sekund
2 2 sekunder
3 4 sekunder
4 8 sekunder

I stedet for å prøve på nytt hvert sekund, venter applikasjonen gradvis lenger.

Å legge til en liten tilfeldig variasjon, kalt jitter, bidrar til å forhindre at mange klienter prøver på nytt samtidig.

Her er en gjenbrukbar forsinkelsesfunksjon:

<?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 bruker full jitter: den faktiske forsinkelsen velges tilfeldig mellom null og det eksponentielle taket.

Den tilfeldige forsinkelsen reduserer synkroniserte utbrudd av nye forsøk, selv om den ikke erstatter en eksplisitt Retry-After-instruksjon gitt av serveren.

Illustration of the article's main concept

5. Bygg en gjenbrukbar PHP API-klient

La oss kombinere de foregående konseptene i en fungerende implementering.

Klienten vår vil:

  • Sette tidsavbrudd for tilkobling og den samlede forespørselen.
  • Returnere HTTP-statusen og svarkroppen.
  • Gjenkjenne overføringsfeil.
  • Prøve utvalgte midlertidige feil på nytt.
  • Respektere Retry-After når den er til stede.
  • Begrense antallet forsøk.
  • Unngå å prøve ikke-idempotente operasjoner på nytt automatisk.
<?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.'
    );
}

Slik bruker 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 implementeringen er med vilje begrenset til GET-forespørsler mot betrodde API-endepunkter.

Den prøver ikke automatisk POST-, PUT-, PATCH- eller DELETE-operasjoner på nytt, fordi disse krever ytterligere sikringstiltak.

Den returnerer også ikke-gjenopprettelige HTTP-svar til kallereren, som må bestemme hvordan de skal håndteres.

For produksjonssystemer bør du i tillegg validere svartypene, håndheve grenser for svarsstørrelse, og skille gjenopprettelige overføringsfeil fra permanente TLS- eller konfigurasjonsfeil.

6. Hvorfor det kan være farlig å prøve POST-forespørsler på nytt

Tenk deg en e-handelsapplikasjon som sender denne forespørselen:

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

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

Den eksterne API-en oppretter ordren, men tilkoblingen brytes før applikasjonen din mottar svaret.

Applikasjonen din ser et tidsavbrudd.

Mislyktes ordren?

Ikke nødvendigvis. Ordren kan allerede finnes.

Hvis applikasjonen din prøver på nytt umiddelbart, kan den opprette en andre ordre.

Dette er grunnen til at et tidsavbrudd ikke beviser at en operasjon mislyktes på serveren.

Bruk idempotensnøkler når de støttes

Noen API-er støtter idempotensnøkler.

For eksempel:

Idempotency-Key: order-8f7a2c

Når API-en tilbyr en dokumentert idempotensmekanisme, kan gjenbruk av samme nøkkel for nye forsøk på samme logiske operasjon forhindre duplikatbehandling.

Men denne oppførselen er API-spesifikk. Å legge til et Idempotency-Key-hodefelt gjør ikke automatisk en vilkårlig API idempotent.

For operasjoner som involverer betalinger, ordrer, abonnementer eller databaseendringer, følg leverandørens offisielle dokumentasjon for nye forsøk og idempotens.

Når ingen idempotensmekanisme finnes, kan du trenge å spørre om operasjonens status eller avstemme resultater før du prøver igjen.

7. Unngå å sove inne i langvarige web-forespørsler

Technical workflow illustration

Eksemplet vårt bruker usleep() for å gjøre oppførselen ved nye forsøk lett å forstå.

Det kan være akseptabelt for korte operasjoner med et stramt kontrollert budsjett for nye forsøk.

Men et produksjonsnettsted bør ikke holde PHP-arbeidere opptatt i minutter mens det venter på en ekstern API.

Anta at en API svarer med:

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

Å vente i én time inne i en HTTP-forespørsel ville være en dårlig design.

En bedre løsning er å utsette operasjonen.

For eksempel, lagre en ventende jobb:

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

En planlagt arbeider kan deretter behandle jobben når den blir kvalifisert.

Denne tilnærmingen er spesielt nyttig for:

  • Synkronisering av produktkatalog.
  • Levering av e-post.
  • Publisering på sosiale medier.
  • Dokumentbehandling.
  • Lageroppdateringer.
  • Store API-importer.

Den gjør det også enklere å overvåke og gjenopprette feil.

8. Lagre informasjon om nye forsøk i en database

For en MariaDB-basert applikasjon kan en enkel jobbtabell se ut som dette:

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

Arbeideren velger jobber der:

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 bare valgdelen av en køimplementering.

Hvis flere arbeidere kan kjøre samtidig, må jobber hentes atomisk, ved å bruke en passende transaksjons- og låsestrategi, for å forhindre duplikatbehandling.

Arbeideren bør også bruke et maksimalt antall nye forsøk og flytte jobber som feiler permanent inn i en tilstand som krever undersøkelse.

For en liten applikasjon kan denne databasebaserte tilnærmingen være tilstrekkelig uten å introdusere Redis eller en dedikert meldingsmegler.

9. Logg feil uten å eksponere sensitive data

En nyttig API-logg bør besvare fire spørsmål:

  1. Hvilken operasjon mislyktes?
  2. Hvilken ekstern tjeneste var involvert?
  3. Hva var HTTP-statusen eller overføringsfeilen?
  4. Når prøver applikasjonen på nytt?

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

Unngå å logge API-nøkler, bearer-tokens, fulle autorisasjonshodefelt, passord eller unødvendig personlig informasjon.

Hvis du trenger å korrelere forespørsler, bruk en generert forespørselsidentifikator.

For eksempel:

$requestId = bin2hex(random_bytes(8));

Du kan inkludere denne identifikatoren i applikasjonslogger og, når det støttes, sende den til den eksterne API-en.

10. Test strategien din for nye forsøk før produksjon

En mekanisme for nye forsøk bør testes mot forutsigbare feilscenarier.

Du trenger ikke å vente på et ekte API-brudd.

Et lokalt testendepunkt kan med vilje returnere spesifikke 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',
]);

Kjør dette endepunktet kun i et lokalt eller beskyttet testmiljø.

Verifiser deretter at klienten din:

  • Gjenkjenner HTTP 429.
  • Leser Retry-After-hodefeltet.
  • Venter før den prøver på nytt.
  • Stopper etter det konfigurerte antallet forsøk.
  • Registrerer feilen uten å eksponere hemmeligheter.

Gjenta med HTTP 503 og et med vilje tregt endepunkt.

Test også et HTTP 400-svar for å bekrefte at klienten ikke prøver permanente forespørselsfeil på nytt.

Til slutt, test en operasjon som kan ha lykkes før tilkoblingen feilet. Dette er avgjørende for betalings- og ordreintegrasjoner.

11. En produksjonssjekkliste for pålitelige API-integrasjoner

Før du distribuerer en API-integrasjon, verifiser følgende:

Sjekk Forventet oppførsel
Tidsavbrudd for tilkobling Definert og testet
Samlet tidsavbrudd Definert og testet
HTTP 429 Respekterer hastighetsgrenser
HTTP 5xx Prøver på nytt selektivt
HTTP 4xx Ingen blinde nye forsøk
Grense for nye forsøk Forhindrer endeløse løkker
Forsinkelse for nye forsøk Tilbakegang med jitter
POST-operasjoner Idempotens eller avstemming
Lange ventetider Utsatt til en arbeider
Logger Nyttige, private, saniterte
Arbeider-konkurranse Duplikat utførelse forhindret
Permanente feil Synlige og gjenopprettelige

Konklusjon: pålitelige API-er krever kontrollert feilhåndtering

Eksterne API-er er aldri perfekt tilgjengelige.

Selv en godt vedlikeholdt tjeneste kan oppleve midlertidig overbelastning, nettverksavbrudd eller hastighetsbegrensning.

Målet er ikke å eliminere hver feil. Det er å få applikasjonen din til å reagere forutsigbart når feil oppstår.

Start med fornuftige tidsavbrudd og eksplisitt HTTP-feilhåndtering. Legg til begrensede nye forsøk med eksponentiell tilbakegang, respekter server-gitte forsinkelser for nye forsøk, og unngå å automatisk gjenta operasjoner som kan opprette dupliserte data.

For mer komplekse integrasjoner, flytt nye forsøk inn i en vedvarende jobbkø i stedet for å holde web-forespørsler åpne.

Disse prinsippene gjelder for nesten hver moderne PHP-applikasjon, enten du bygger en CMS-utvidelse, synkroniserer en e-handelskatalog, sender transaksjonelle e-poster eller integrerer en betalingstjeneste.

En pålitelig API-klient er en som vet ikke bare hvordan man sender en forespørsel, men også når man skal prøve på nytt, når man skal vente, og når man skal stoppe.

Offisielle referanser