Hur man hanterar API-tidsgränser, hastighetsbegränsningar och återförsök i PHP
Lär dig hur du bygger pålitliga PHP API-integrationer med anslutningstidsgränser, HTTP-felhantering, exponentiell backoff, Retry-After-stöd och säkra återförsökstrategier.
Så hanterar du API-timeouts, rate limits och återförsök i PHP
En API-integration fungerar perfekt under utveckling. Sedan, en dag, stannar din schemalagda uppgift halvvägs. En fjärrtjänst svarar med HTTP 429, en anslutning får timeout, eller ett HTTP 503-fel avbryter en synkronisering.
Frestelsen är att försöka igen med begäran direkt.
Men att försöka igen utan en strategi kan göra problemet värre. Det kan överbelasta en redan kämpande API, överskrida rate limits, eller av misstag skapa dubbla order och betalningar.
En pålitlig API-klient behöver mer än ett lyckat curl_exec()-anrop.
I den här handledningen bygger vi en praktisk PHP HTTP-klient som hanterar anslutnings-timeouts, HTTP-fel, rate limits och tillfälliga fel. Vi förklarar också när det är säkert att försöka igen, när det inte är det, och hur man diagnostiserar problem i produktion.
Exemplen använder PHP:s inbyggda cURL-tillägg, utan Composer eller tredjepartsberoenden.
1. Förstå de olika typerna av API-fel
Inte varje misslyckad begäran bör hanteras på samma sätt.
| Fel | Typisk orsak | Rekommenderad åtgärd |
|---|---|---|
| Anslutnings-timeout | Servern är o nåbar eller anslutningen är långsam | Försök igen försiktigt |
| HTTP 400 | Ogiltiga begärandeparametrar | Fixa begäran |
| HTTP 401 | Ogiltiga eller utgångna autentiseringsuppgifter | Kontrollera autentiseringen |
| HTTP 404 | Resursen hittades inte | Kontrollera resursidentifieraren |
| HTTP 429 | API-rate limit överskriden | Respektera Retry-After |
| HTTP 500 | Internt serverfel | Försök igen selektivt |
| HTTP 503 | Tillfällig otillgänglighet i tjänsten | Försök igen med fördröjning |
| Ogiltig JSON | Oväntat svarsformat | Logga och undersök |
Ett nätverksfel skiljer sig också från ett HTTP-fel.
När en API returnerar HTTP 500 har HTTP-begäran slutförts och servern returnerade ett felmeddelande.
När cURL rapporterar ett anslutningsfel kan din applikation inte ha fått något HTTP-svar alls.
Den åtskillnaden spelar roll när man bestämmer huruvida man ska försöka igen.
2. Konfigurera alltid anslutnings- och begärandetimeouts
PHP cURL tillhandahåller två särskilt användbara inställningar:
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,
CURLOPT_CONNECTTIMEOUT begränsar anslutningsfasen, medan CURLOPT_TIMEOUT begränsar den totala överföringsdurationen. Båda är dokumenterade i PHP:s officiella cURL-referens.
Utan lämpliga gränser kan en långsam extern tjänst uppta PHP-workers mycket längre än förväntat.
En praktisk utgångspunkt för en konventionell JSON-API kan vara fem sekunder för att etablera anslutningen och femton sekunder för hela begäran.
Det här är inte universella värden. En filuppladdning eller generering av en långkörande rapport kan behöva en annan timeout-policy.
Gör din första API-begäran
<?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;
Detta etablerar en användbar grund, men det hanterar ännu inte rate limits eller återförsökbara fel.
3. Förstå HTTP 429 och Retry-After
HTTP 429 betyder att klienten har skickat för många begäranden inom en period som definieras av API-leverantören.
Vissa API:er inför gränser per minut, per timme, per API-nyckel eller per konto.
En server kan svara med:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
Retry-After-headern talar om för klienten hur länge den bör vänta innan den försöker igen.
Headern kan innehålla antingen ett antal sekunder eller ett HTTP-datum.
Till exempel:
Retry-After: 120
Eller:
Retry-After: Wed, 25 Nov 2026 10:00:00 GMT
En väluppfostrad klient bör respektera denna instruktion istället för att upprepade gånger skicka begäranden.
Om servern inte tillhandahåller någon fördröjning för återförsök behöver din applikation en reservstrategi.
4. Använd exponentiell backoff istället för omedelbara återförsök
Exponentiell backoff ökar väntetiden efter på varandra följande fel.
Till exempel:
| Försök | Exempelfördröjning |
|---|---|
| 1 | 1 sekund |
| 2 | 2 sekunder |
| 3 | 4 sekunder |
| 4 | 8 sekunder |
Istället för att försöka igen varje sekund väntar applikationen allt längre.
Att lägga till en liten slumpmässig variation, kallad jitter, hjälper till att förhindra att många klienter försöker igen samtidigt.
Här är en återanvändbar fördröjningsfunktion:
<?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
);
}
Detta använder full jitter: den faktiska fördröjningen väljs slumpmässigt mellan noll och det exponentiella taket.
Den slumpmässiga fördröjningen minskar synkroniserade återförsöksburstar, även om den inte ersätter en explicit Retry-After-instruktion från servern.

5. Bygg en återanvändbar PHP API-klient
Låt oss kombinera de föregående koncepten i en fungerande implementation.
Vår klient kommer att:
- Ställa in anslutnings- och totala begärandetimeouts.
- Returnera HTTP-status och svarskropp.
- Upptäcka transportfel.
- Försöka igen med utvalda tillfälliga fel.
- Respektera
Retry-Afternär den finns. - Begränsa antalet försök.
- Undvika att automatiskt försöka igen med icke-idempotenta operationer.
<?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.'
);
}
Hur man använder 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());
}
Denna implementation är medvetet begränsad till GET-begäranden mot betrodda API-slutpunkter.
Den försöker inte automatiskt igen med POST-, PUT-, PATCH- eller DELETE-operationer, eftersom de kräver ytterligare skyddsåtgärder.
Den returnerar också icke-återförsökbara HTTP-svar till anroparen, som måste bestämma hur de ska hanteras.
För produktionssystem bör du dessutom validera svarstyper, upprätthålla gränser för svarsstorlek och skilja återförsökbara transportfel från permanenta TLS- eller konfigurationsfel.
6. Varför det kan vara farligt att försöka igen med POST-begäranden
Föreställ dig en e-handelsapplikation som skickar denna begäran:
POST /api/orders
Content-Type: application/json
{
"product_id": 42,
"quantity": 1
}
Den externa API:n skapar ordern, men anslutningen bryts innan din applikation får svaret.
Din applikation ser en timeout.
Misslyckades ordern?
Inte nödvändigtvis. Ordern kan redan finnas.
Om din applikation omedelbart försöker igen kan den skapa en andra order.
Detta är varför en timeout inte bevisar att en operation misslyckades på servern.
Använd idempotensnycklar när de stöds
Vissa API:er stöder idempotensnycklar.
Till exempel:
Idempotency-Key: order-8f7a2c
När API:n tillhandahåller en dokumenterad idempotensmekanism kan återanvändning av samma nyckel för återförsök av samma logiska operation förhindra dubbel bearbetning.
Men detta beteende är API-specifikt. Att lägga till en Idempotency-Key-header gör inte automatiskt en godtycklig API idempotent.
För operationer som involverar betalningar, order, prenumerationer eller databasändringar, följ leverantörens officiella dokumentation om återförsök och idempotens.
När ingen idempotensmekanism finns kan du behöva efterfråga operationens status eller stämma av resultat innan du försöker igen.
7. Undvik att sova inuti långkörande webbförfrågningar

Vårt exempel använder usleep() för att göra återförsöksbeteendet lätt att förstå.
Det kan vara acceptabelt för korta operationer med en tätt kontrollerad budget för återförsök.
Men en produktionswebbplats bör inte hålla PHP-workers upptagna i minuter medan den väntar på en extern API.
Anta att en API svarar med:
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Att vänta en timme inuti en HTTP-begäran vore en dålig design.
En bättre lösning är att skjuta upp operationen.
Till exempel, lagra en väntande uppgift:
Job ID: 1842
Status: pending
Attempts: 2
Next attempt: 2026-11-20 14:30:00 UTC
En schemalagd worker kan sedan bearbeta uppgiften när den blir berättigad.
Detta tillvägagångssätt är särskilt användbart för:
- Synkronisering av produktkataloger.
- E-postleverans.
- Publicering på sociala medier.
- Dokumentbearbetning.
- Lageruppdateringar.
- Stora API-importer.
Det gör också fel lättare att övervaka och återhämta.
8. Lagra information om återförsök i en databas
För en MariaDB-baserad applikation kan en enkel uppgiftstabell se ut så här:
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
)
);
Workern väljer uppgifter där:
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;
Detta är bara urvals delen av en köimplementation.
Om flera workers kan köras samtidigt måste uppgifter göras anspråk på atomiskt, med en lämplig transaktions- och låsningsstrategi, för att förhindra dubbel bearbetning.
Workern bör också tillämpa ett maximalt antal återförsök och flytta permanent misslyckade uppgifter till ett tillstånd som kräver utredning.
För en liten applikation kan detta databasbaserade tillvägagångssätt vara tillräckligt utan att introducera Redis eller en dedikerad meddelandehanterare.
9. Logga fel utan att exponera känslig data
En användbar API-logg bör svara på fyra frågor:
- Vilken operation misslyckades?
- Vilken fjärrtjänst var inblandad?
- Vad var HTTP-statusen eller transportfelet?
- När kommer applikationen att försöka igen?
Till exempel:
[2026-11-20 13:25:00 UTC]
service=inventory-api
operation=sync-products
status=429
attempt=2
next_retry=2026-11-20T13:26:00Z
Undvik att logga API-nycklar, bearer tokens, fullständiga auktoriseringsheaders, lösenord eller onödig personlig information.
Om du behöver korrelera begäranden, använd ett genererat begärande-ID.
Till exempel:
$requestId = bin2hex(random_bytes(8));
Du kan inkludera denna identifierare i applikationsloggar och, när det stöds, skicka den till den externa API:n.
10. Testa din återförsöksstrategi före produktion
En återförsöksmekanism bör testas mot förutsägbara felfall.
Du behöver inte vänta på ett verkligt API-avbrott.
En lokal testslutpunkt kan medvetet returnera specifika statuskoder.
Till exempel:
<?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 endast denna slutpunkt i en lokal eller skyddad testmiljö.
Verifiera sedan att din klient:
- Upptäcker HTTP 429.
- Läser
Retry-After-headern. - Väntar innan den försöker igen.
- Stannar efter det konfigurerade antalet försök.
- Registrerar felet utan att exponera hemligheter.
Upprepa med HTTP 503 och en medvetet långsam slutpunkt.
Testa också ett HTTP 400-svar för att bekräfta att klienten inte försöker igen med permanenta begärandefel.
Slutligen, testa en operation som kan ha lyckats innan anslutningen bröts. Detta är avgörande för betalnings- och orderintegrationer.
11. En produktionschecklista för pålitliga API-integrationer
Innan du driftsätter en API-integration, verifiera följande:
| Kontroll | Förväntat beteende |
|---|---|
| Anslutnings-timeout | Definierad och testad |
| Total timeout | Definierad och testad |
| HTTP 429 | Respekterar rate limits |
| HTTP 5xx | Försöker igen selektivt |
| HTTP 4xx | Inga blinda återförsök |
| Återförsöksgräns | Förhindrar oändliga loopar |
| Återförsöksfördröjning | Backoff med jitter |
| POST-operationer | Idempotens eller avstämning |
| Långa väntetider | Schemalagda till en worker |
| Loggar | Användbara, privata, sanerade |
| Worker-konkurrens | Dubbel exekvering förhindrad |
| Permanenta fel | Synliga och återhämtningsbara |
Slutsats: pålitliga API:er kräver kontrollerad felhantering
Externa API:er är aldrig perfekt tillgängliga.
Även en välunderhållen tjänst kan uppleva tillfällig överbelastning, nätverksavbrott eller rate limiting.
Målet är inte att eliminera varje fel. Det är att få din applikation att svara förutsägbart när fel inträffar.
Börja med rimliga timeouts och explicit hantering av HTTP-fel. Lägg till begränsade återförsök med exponentiell backoff, respektera fördröjningar för återförsök från servern, och undvik att automatiskt upprepa operationer som kan skapa dubblettdata.
För mer komplexa integrationer, flytta återförsök till en persistent uppgiftskö istället för att hålla webbförfrågningar öppna.
Dessa principer gäller för nästan varje modern PHP-applikation, oavsett om du bygger ett CMS-tillägg, synkroniserar en e-handelskatalog, skickar transaktionella e-postmeddelanden eller integrerar en betaltjänst.
En pålitlig API-klient är en som inte bara vet hur man skickar en begäran, utan också när man ska försöka igen, när man ska vänta, och när man ska sluta.