Verkkosivut ja kehitys

Kuinka käsitellä API:n aikakatkaisuja, rajoituksia ja uudelleenyrityksiä PHP:lla

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

Opi rakentamaan luotettavia PHP API -integraatioita yhteysajan aikakatkaisuilla, HTTP-virheenkäsittelyllä, eksponentiaalisella viiveellä, Retry-After-tuen ja turvallisten uudelleenyrityssääntöjen avulla.

Miten käsitellä API-aikakatkaisuja, nopeusrajoituksia ja uudelleenyrityksiä PHP:ssä

API-integraatio toimii täydellisesti kehitysvaiheessa. Sitten, jossain päivänä, aikataulutettu tehtys keskeytyy puolessa välissä. Jauhkoton palvelu vastaa HTTP 429:lla, yhteys aikakatkaisee tai HTTP 503 -virhe keskeyttää synkronoinnin.

Vetona on yrittää pyyntöä heti uudelleen.

Mutta uudelleenyritys ilman strategiaa voi pahemmatta ongelmaa. Se voi ylikuormittaa jo taistelleen API:n, ylittää nopeusrajoitukset tai vahingossa luoda kaksoistilauksia ja -maksut.

Luotettava API-asiakas tarvitsee enemmän kuin onnistuneen curl_exec()-kutsun.

Tässä opetusohjelmassa rakentamme käytännön PHP HTTP-asiakkaan, joka käsittelee yhteysaikakatkaisut, HTTP-virheet, nopeusrajoitukset ja tilapäiset virheet. Selitämme myös, milloin uudelleenyritys on turvallista, milloin se ei ole, ja miten diagnosoida ongelmia tuotannossa.

Esimerkit käyttävät PHP:n sisäänrakennettua cURL-laajennusta ilman Composeria tai kolmannen osapuolen riippuvuuksia.

1. Ymmärrä eri tyyppiset API-virheet

Ei jokainen epäonnistunut pyyntö pitäisi käsitellä samalla tavalla.

Virhe Tyypillinen syy Suositeltu toiminto
Yhteysaikakatkaisu Palvelin saavuttamaton tai hidas yhteys Yritä uudelleen varovasti
HTTP 400 Virheelliset pyyntöparametrit Korjaa pyyntö
HTTP 401 Virheelliset tai vanhentuneet tunnistetiedot Tarkista todennus
HTTP 404 Resurssia ei löydy Tarkista resurssin tunniste
HTTP 429 API-nopeusrajoitus ylitetty kunnioita Retry-After
HTTP 500 Sisäinen palvelinvirhe Yritä uudelleen valikoivasti
HTTP 503 Tilapäinen palvelun epäoleellisuus Yritä uudelleen viiveellä
Virheellinen JSON Odottamaton vastausmuoto Kirjaa ja tutki

Verkkovirhe on myös erilainen kuin HTTP-virhe.

Kun API palauttaa HTTP 500:n, HTTP-pyyntö on suoritettu ja palvelin on palauttanut virhevastauksen.

Kun cURL raportoi yhteysvirheen, sovelluksesi saattoi olla saanut ei yhtään HTTP-vastausta.

Tämä ero on merkityksellinen päättäessä, onko uudelleenyritys järkevää.

2. Määritä aina yhteys- ja pyyntöaikakatkaisut

PHP cURL tarjoaa kaksi erityisen hyödyllistä asetusta:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT rajoittaa yhteyden muodostamisen vaihetta, kun CURLOPT_TIMEOUT rajoittaa kokonaisen siirron kestoa. Molemmat on dokumentoitu PHP:n virallisessa cURL-viittauksessa.

Ilman sopivia rajoja hidas ulkoinen palvelu voi varata PHP-työntekijät kauemmaksi kuin odotettu.

Perinteiselle JSON-API:lle käytännöllinen alkupiste voi olla viisi sekuntia yhteyden muodostamiselle ja viisitoista sekuntia kokonaiselle pyynnölle.

Nämä eivät ole universaaleja arvoja. Tiedoston lataaminen tai pitkäkestoinen raportin generointi saattavat vaatia erilaisen aikakatkaisukäytännön.

Tee ensimmäinen API-pyytösi

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

Tämä luo hyödyllisen perustan, mutta se ei vielä käsittele nopeusrajoituksia tai uudelleenyritykseen sopivia virheitä.

3. Ymmärrä HTTP 429 ja Retry-After

HTTP 429 tarkoittaa, että asiakas on lähettänyt liian monta pyyntöä API-toimittajan määrittämänä aikana.

Jotkut API:t asettavat rajoituksia minuutissa, tunnissa, API-avainta tai tiliä kohden.

Palvelin voi vastata:

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

Retry-After-otsakkeen kertoo asiakkaalle, kuinka kauan se pitää odottaa ennen uudelleenyritystä.

Otsakkeen sisältö voi olla joko sekuntien määrä tai HTTP-päivämäärä.

Esimerkiksi:

Retry-After: 120

Tai:

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

Hyvin käyttäytyvä asiakas pitäisi noudattaa tätä ohjetta sen sijaan, että se lähettäisi pyyntöjä toistuvasti.

Jos palvelin ei anna uudelleenyritysviivettä, sovelluksesi tarvitsee varmistrategian.

4. Käytä eksponentiaalista takaisinaskelua välitön uudelleenyrityksen sijaan

Eksponentiaalinen takaisinaskelu pidentää odotusaikaa peräkkäisten virheiden jälkeen.

Esimerkiksi:

Uudelleenyritys Esimerkkiviive
1 1 sekunti
2 2 sekuntia
3 4 sekuntia
4 8 sekuntia

Sijasta, että yrittäisi joka sekunti, sovellus odottaa progressiivisesti kauemmin.

Pienen satunnaisen vaihtelun, niin kutsutun jitterin, lisääminen estää monia asiakkaita yrittämästä samanaikaisesti.

Tässä on uudelleenkäytettävä viivefunktio:

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

Tämä käyttää täyttä jitteriä: todellinen viive valitaan satunnaisesti nollan ja eksponentiaalisen kynnysarvon väliltä.

Satunnainen viive vähentää synkronoituja uudelleenyrityspommituksia, vaikka se ei korvaa palvelimen antamaa eksplisiittistä Retry-After-ohjetta.

Illustration of the article's main concept

5. Rakenna uudelleenkäytettävä PHP API-asiakas

Yhdistämme edelliset käsitteet toimivaksi toteutukseksi.

Asiakkaamme:

  • Määrittää yhteys- ja kokonaispyyntöaikakatkaisut.
  • Palauttaa HTTP-tilan ja vastauksen rungon.
  • Havaitsee siirtovirheet.
  • Yrittää uudelleen valitut tilapäiset virheet.
  • Kunnioittaa Retry-After:ta, kun se on olemassa.
  • Rajoittaa yritysten määrää.
  • Vältää epäidempotenttien operaatioiden automaattisen uudelleenyrityksen.
<?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.'
    );
}

Miten käyttää sitä

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

Tämä toteutus on tarkoituksella rajoitettu GET-pyyntöihin luotettavia API-päätepisteitä vasten.

Se ei automaattisesti yritä uudelleen POST-, PUT-, PATCH- tai DELETE-operaatioita, koska ne vaativat lisävahvistuksia.

Se palauttaa myös uudelleenyritykseen sopimattomat HTTP-vastaukset kutsujalle, joka päättää, miten niitä käsitellään.

Tuotantojärjestelmissä sinun tulisi lisäksi vahvistaa vastausmuodot, asettaa vastauksen koon rajoitukset ja erottaa uudelleenyritykseen sopivat siirtovirheet pysyvistä TLS- tai kokoonpanovirheistä.

6. Miksi POST-pyyntöjen uudelleenyritys voi olla vaarallista

Kuvittele verkkokaupasovellus, joka lähettää tämän pyynnön:

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

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

Ulkoinen API luo tilauksen, mutta yhteys katkeaa ennen kuin sovelluksesi saa vastauksen.

Sovelluksesi näkee aikakatkaisun.

Epäonnistuiko tilaus?

Ei välttämättä. Tilaus saattaa jo olla olemassa.

Jos sovelluksesi yrittää heti uudelleen, se saattaa luoda toisen tilauksen.

Tämä on syy siihen, miksi aikakatkaisu ei todista, että operaatio epäonnistui palvelimella.

Käytä idempotenssiavainta, kun se on tuettu

Jotkut API:t tukevat idempotenssiavainta.

Esimerkiksi:

Idempotency-Key: order-8f7a2c

Kun API tarjoaa dokumentoidun idempotenssimekanismin, saman avaimen uudelleenkäyttö saman loogisen operaatio uudelleenyrityksissä voi estää kaksoiskäsittelyn.

Mutta tämä käyttäytyminen on API-kohtaista. Idempotency-Key-otsakkeen lisääminen ei automaattisesti tee mielivaltaisesta API:sta idempotentti.

Maksuihin, tilauksiin, tilauksiin tai tietokantamuutoksiin liittyvissä operaatioissa noudata toimittajan virallista uudelleenyritys- ja idempotenssi-dokumentaatioa.

Kun idempotenssimekanismia ei ole, sinun saattaa olla kysyttävä operaation tila tai sovittaa tulokset ennen uudelleenyritystä.

7. Vältä nukkumista pitkäkestoisissa verkkopyynnöissä

Technical workflow illustration

Esimerkkiämme käyttää usleep():ta tehdäkseen uudelleenyrityskäyttäytymisestä helppoa ymmärtää.

Se voi olla hyväksyttävää lyhyille operaatioille, joilla on tiukasti hallittu uudelleenyritysbudjetti.

Kuitenkin tuotannon verkkosivusto ei pitäisi pitää PHP-työntekijöitä varattuna minuuteiksi odottaessa ulkoista API:a.

Oletetaan, että API vastaa:

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

Yhden tunnin odottaminen HTTP-pyynnön sisällä olisi huono suunnittelu.

Parempi ratkaisu on siirtää operaatio myöhemmäksi.

Esimerkiksi tallenna odottava työn:

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

Aikataulutettu työntekijä voi sitten käsitellä työn, kun se on oikeutettu.

Tämä lähestymistapa on erityisen hyödyllinen:

  • Tuotekatalogin synkronoinnissa.
  • Sähköpostien toimituksessa.
  • Sosiaalisen median julkaisemisessa.
  • Dokumenttien käsittelyssä.
  • Varastopäivityksissä.
  • Suurissa API-tuonnoissa.

Se myös helpottaa virheiden valvonta ja palautusta.

8. Tallenna uudelleenyritystietokantaan

MariaDB-pohjaiselle sovellukselle yksinkertainen työtäulu voisi näyttää tältä:

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

Työntekijä valitsee työt, joissa:

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;

Tämä on vain jonon toteutuksen valintaoosa.

Jos useita työntekijöitä voi toimia samanaikaisesti, työt on otettava hallintaan atomisesti, käyttäen sopivaa transaktio- ja lukitusstrategiaa, kaksoiskäsittelyn estämiseksi.

Työntekijän tulisi myös soveltaa enimmäisuudelleenyritysmäärää ja siirtää pysyvästi epäonnistuvat työt tilaan, joka vaatii tutkimista.

Pienelle sovellukselle tämä tietokantapohjainen lähestymistapa voi olla riittävä ilman Redisin tai erillisen viestivälittäjän介绍.

9. Kirjaa virheet ilman herkän datan paljastamista

Hyödyllinen API-loki tulisi vastata neljään kysymykseen:

  1. Mikä operaatio epäonnistui?
  2. Minkä kaukoon palvelu oli mukana?
  3. Mikä oli HTTP-tila tai siirtovirhe?
  4. Milloin sovellus yrittää uudelleen?

Esimerkiksi:

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

Vältä API-avainten, bearer-tokenien, täydellisten authorization-otsakkeiden, salasanojen tai tarpeettoman henkilötietojen kirjaamista.

Jos sinun on korreloitava pyyntöjä, käytä generoitua pyyntötunnistetta.

Esimerkiksi:

$requestId = bin2hex(random_bytes(8));

Voit sisällyttää tämän tunnisteen sovelluslokeihin ja, kun se on tuettu, lähettää sen kaukoon API:lle.

10. Testaa uudelleenyritysstrategiasi ennen tuotantoa

Uudelleenyritysmekanismia tulisi testata ennakolta ennustettavien virheskenaarioiden vastaan.

Et tarvitse odottaa oikeaa API-keskeytykset.

Paikallinen testipäätepiste voi tarkoituksella palauttaa tiettyjä tilakoodia.

Esimerkiksi:

<?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äytä tätä päätepistettä vain paikallisessa tai suojatussa testiympäristössä.

Varmista sitten, että asiakkaasi:

  • Havaitsee HTTP 429:n.
  • Lukee Retry-After-otsakkeen.
  • Odottaa ennen uudelleenyritystä.
  • Pysähtyy määritetyn yritysten määrän jälkeen.
  • Kirjaa virheen ilman salaisuuksien paljastamista.

Toista HTTP 503:lla ja tarkoituksella hitaalla päätepisteellä.

Testaa myös HTTP 400 -vastausta varmistaaksesi, että asiakas ei yritä uudelleen pysyviä pyyntövirheitä.

Lopuksi testaa operaatio, joka saattoi onnistua ennen yhteyden katkeamista. Tämä on olennainen maksu- ja tilausintegraatioissa.

11. Tuotantovalmistelulista luotettaviin API-integraatioihin

Ennen API-integraation käyttöönottoa, varmista seuraavat:

Tarkistus Odotettu käyttäytyminen
Yhteysaikakatkaisu Määritelty ja testattu
Kokonaisaikakatkaisu Määritelty ja testattu
HTTP 429 Kunnioittaa nopeusrajoituksia
HTTP 5xx Yrittää uudelleen valikoivasti
HTTP 4xx Ei sokeita uudelleenyrityksiä
Uudelleenyritysraja Estää loputtomat silmukat
Uudelleenyritysviive Takaisinaskelu jitterillä
POST-operaatiot Idempotenssi tai sovittelu
Pitkäkestoiset odotukset Siirretty työntekijälle
Lokit Hyödylliset, yksityiset, siivottu
Työntekijän samanaikaisuus Kaksoissuoritus estetty
Pysyvät virheet Näkyvät ja palautettavat

Johtopäätös: luotettavat API:t vaativat hallittua virheenkäsittelyä

Ulkoiset API:t eivät ole koskaan täydellisesti saatavilla.

Jopa hyvin ylläpidetty palvelu voi kokea tilapäistä ylikuormitusta, verkkokatkoksia tai nopeusrajoitusta.

Tavoitteena ei ole poistaa jokainen virhe. Se on tehdä sovelluksestasi ennustettavasti reagoiva virheitä tapahtuttaessa.

Aloita järkevillä aikakatkaisuilla ja eksplisiittisellä HTTP-virheenkäsittelyllä. Lisää rajoitetut uudelleenyritykset eksponentiaalisella takaisinaskelulla, kunnioita palvelimen antamia uudelleenyritysviiveitä ja vältä automaattista toistoa operaatioille, jotka voivat luoda kaksoisdataa.

Monimutkaisempien integrointien tapauksessa siirrä uudelleenyritykset pysyvään jonon sijaan, että pitäisit verkkopyynnöt avoimina.

Nämä periaatteet soveltuvat lähes jokaiseen moderniin PHP-sovellukseen, olipa kyseessä CMS-laajennuksen rakentaminen, verkkokaupan katalogin synkronointi, transaktionaalisten sähköpostien lähettäminen tai maksunpalvelun integrointi.

Luotettava API-asiakas on se, joka ymmärtää ei vain miten lähettää pyyntö, vaan myös milloin yrittää uudelleen, milloin odottaa ja milloin lopettaa.

Viralliset viittaukset