Kuinka käsitellä API:n aikakatkaisuja, rajoituksia ja uudelleenyrityksiä PHP:lla
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.

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ä

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:
- Mikä operaatio epäonnistui?
- Minkä kaukoon palvelu oli mukana?
- Mikä oli HTTP-tila tai siirtovirhe?
- 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.