Jak obsługiwać opóźnienia API, limity szybkości i ponawianie w PHP
Dowiedz się, jak budować niezawodne integracje API PHP z opóźnieniami połączeń, obsługą błędów HTTP, wykładniczym odświeżaniem, obsługą Retry-After oraz bezpiecznymi strategiami ponawiania.
Jak obsługiwać limity czasu API, limity szybkości i ponawianie prób w PHP
Integracja API działa idealnie podczas tworzenia. Potem pewnego dnia zaplanowane zadanie zatrzymuje się w połowie. Zdalna usługa odpowiada HTTP 429, połączenie przekracza limit czasu albo błąd HTTP 503 przerywa synchronizację.
Pokusa, by natychmiast ponowić żądanie.
Jednak ponawianie bez strategii może pogorszyć problem. Może przeciążyć już przeciążone API, przekroczyć limity szybkości lub przypadkowo utworzyć zduplikowane zamówienia i płatności.
Niezawodny klient API potrzebuje więcej niż udanego wywołania curl_exec().
W tym samouczku zbudujemy praktyczny klient HTTP w PHP, który obsługuje limity czasu połączenia, błędy HTTP, limity szybkości i przejściowe awarie. Wyjaśnimy również, kiedy ponawianie jest bezpieczne, kiedy nie jest i jak diagnozować problemy w środowisku produkcyjnym.
Przykłady wykorzystują wbudowane rozszerzenie cURL w PHP, bez Composera ani zależności zewnętrznych.
1. Zrozum różne typy awarii API
Nie każde nieudane żądanie należy obsługiwać w ten sam sposób.
| Awaria | Typowa przyczyna | Zalecane działanie |
|---|---|---|
| Limit czasu połączenia | Serwer nieosiągalny lub wolne połączenie | Ponawiaj ostrożnie |
| HTTP 400 | Nieprawidłowe parametry żądania | Popraw żądanie |
| HTTP 401 | Nieprawidłowe lub wygasłe dane uwierzytelniające | Sprawdź uwierzytelnianie |
| HTTP 404 | Nie znaleziono zasobu | Sprawdź identyfikator zasobu |
| HTTP 429 | Przekroczono limit szybkości API | Respektuj Retry-After |
| HTTP 500 | Wewnętrzny błąd serwera | Ponawiaj wybiórczo |
| HTTP 503 | Tymczasowa niedostępność usługi | Ponów z opóźnieniem |
| Nieprawidłowy JSON | Nieoczekiwany format odpowiedzi | Zarejestruj i zbadaj |
Błąd sieci różni się również od błędu HTTP.
Gdy API zwraca HTTP 500, żądanie HTTP zostało zakończone, a serwer zwrócił odpowiedź z błędem.
Gdy cURL zgłasza awarię połączenia, aplikacja mogła nie otrzymać żadnej odpowiedzi HTTP.
To rozróżnienie ma znaczenie przy podejmowaniu decyzji, czy ponowić próbę.
2. Zawsze konfiguruj limity czasu połączenia i żądania
PHP cURL udostępnia dwa szczególnie przydatne ustawienia:
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,
CURLOPT_CONNECTTIMEOUT ogranicza fazę połączenia, natomiast CURLOPT_TIMEOUT ogranicza całkowity czas transferu. Oba są udokumentowane w oficjalnym podręczniku cURL dla PHP.
Bez odpowiednich limitów wolna usługa zewnętrzna może zajmować procesy robocze PHP znacznie dłużej niż oczekiwano.
Praktycznym punktem wyjścia dla konwencjonalnego API JSON może być pięć sekund na nawiązanie połączenia i piętnaście sekund na pełne żądanie.
To nie są uniwersalne wartości. Przesyłanie pliku lub długotrwałe generowanie raportu może wymagać innej polityki limitów czasu.
Wykonaj pierwsze żądanie do API
<?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;
To tworzy przydatną podstawę, ale nie obsługuje jeszcze limitów szybkości ani błędów, które można ponowić.
3. Zrozum HTTP 429 i Retry-After
HTTP 429 oznacza, że klient wysłał zbyt wiele żądań w okresie zdefiniowanym przez dostawcę API.
Niektóre API nakładają limity na minutę, godzinę, klucz API lub konto.
Serwer może odpowiedzieć:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
Nagłówek Retry-After informuje klienta, jak długo powinien odczekać przed ponowną próbą.
Nagłówek może zawierać liczbę sekund albo datę HTTP.
Na przykład:
Retry-After: 120
Lub:
Retry-After: Wed, 25 Nov 2026 10:00:00 GMT
Dobrze zachowujący się klient powinien respektować tę instrukcję, zamiast wielokrotnie wysyłać żądania.
Jeśli serwer nie podaje opóźnienia ponowienia, aplikacja potrzebuje strategii awaryjnej.
4. Używaj wykładniczego backoffu zamiast natychmiastowych ponowień
Wykładniczy backoff zwiększa czas oczekiwania po kolejnych awariach.
Na przykład:
| Próba | Przykładowe opóźnienie |
|---|---|
| 1 | 1 sekunda |
| 2 | 2 sekundy |
| 3 | 4 sekundy |
| 4 | 8 sekund |
Zamiast ponawiać co sekundę, aplikacja czeka coraz dłużej.
Dodanie niewielkiej losowej zmienności, zwanej jitterem, pomaga zapobiegać jednoczesnemu ponawianiu przez wielu klientów.
Oto funkcja opóźnienia wielokrotnego użytku:
<?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
);
}
Wykorzystuje ona pełny jitter: rzeczywiste opóźnienie jest losowo wybierane między zerem a wykładniczym limitem.
Losowe opóźnienie zmniejsza zsynchronizowane serie ponowień, chociaż nie zastępuje jawnej instrukcji Retry-After dostarczonej przez serwer.

5. Zbuduj klienta API w PHP wielokrotnego użytku
Połączmy poprzednie koncepcje w działającą implementację.
Nasz klient będzie:
- Ustawiał limity czasu połączenia i całkowitego żądania.
- Zwracał status HTTP i treść odpowiedzi.
- Wykrywał awarie transportu.
- Ponawiał wybrane przejściowe awarie.
- Respektował
Retry-After, gdy jest obecny. - Ograniczał liczbę prób.
- Unikał automatycznego ponawiania nieidempotentnych operacji.
<?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.'
);
}
Jak go używać
<?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());
}
Ta implementacja jest celowo ograniczona do żądań GET kierowanych do zaufanych punktów końcowych API.
Nie ponawia automatycznie operacji POST, PUT, PATCH ani DELETE, ponieważ wymagają one dodatkowych zabezpieczeń.
Zwraca również wywołującemu odpowiedzi HTTP, których nie można ponowić, a on musi zdecydować, jak je obsłużyć.
W systemach produkcyjnych należy dodatkowo sprawdzać typy odpowiedzi, wymuszać limity rozmiaru odpowiedzi i odróżniać błędy transportu, które można ponowić, od trwałych awarii TLS lub konfiguracji.
6. Dlaczego ponawianie żądań POST może być niebezpieczne
Wyobraź sobie aplikację e-commerce wysyłającą to żądanie:
POST /api/orders
Content-Type: application/json
{
"product_id": 42,
"quantity": 1
}
Zdalne API tworzy zamówienie, ale połączenie zostaje przerwane, zanim aplikacja otrzyma odpowiedź.
Aplikacja widzi przekroczenie limitu czasu.
Czy zamówienie się nie udało?
Niekoniecznie. Zamówienie może już istnieć.
Jeśli aplikacja natychmiast ponowi próbę, może utworzyć drugie zamówienie.
Właśnie dlatego przekroczenie limitu czasu nie dowodzi, że operacja nie powiodła się po stronie serwera.
Używaj kluczy idempotentności, gdy są obsługiwane
Niektóre API obsługują klucze idempotentności.
Na przykład:
Idempotency-Key: order-8f7a2c
Gdy API udostępnia udokumentowany mechanizm idempotentności, ponowne użycie tego samego klucza dla ponowień tej samej operacji logicznej może zapobiec podwójnemu przetworzeniu.
Jednak takie zachowanie zależy od konkretnego API. Dodanie nagłówka Idempotency-Key nie czyni automatycznie dowolnego API idempotentnym.
W przypadku operacji dotyczących płatności, zamówień, subskrypcji lub modyfikacji bazy danych należy postępować zgodnie z oficjalną dokumentacją dostawcy dotyczącą ponowień i idempotentności.
Gdy nie istnieje mechanizm idempotentności, może być konieczne sprawdzenie statusu operacji lub uzgodnienie wyników przed ponowieniem próby.
7. Unikaj usypiania w długotrwałych żądaniach internetowych

Nasz przykład używa usleep(), aby ułatwić zrozumienie zachowania ponowień.
Może to być akceptowalne w przypadku krótkich operacji ze ściśle kontrolowanym budżetem ponowień.
Jednak witryna produkcyjna nie powinna zajmować procesów roboczych PHP przez minuty w oczekiwaniu na zewnętrzne API.
Załóżmy, że API odpowiada:
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Oczekiwanie godziny w ramach żądania HTTP byłoby złym projektem.
Lepszym rozwiązaniem jest odroczenie operacji.
Na przykład zapisz oczekujące zadanie:
Job ID: 1842
Status: pending
Attempts: 2
Next attempt: 2026-11-20 14:30:00 UTC
Zaplanowany proces roboczy może następnie przetworzyć zadanie, gdy stanie się kwalifikowalne.
To podejście jest szczególnie przydatne w przypadku:
- Synchronizacji katalogu produktów.
- Dostarczania e-maili.
- Publikowania w mediach społecznościowych.
- Przetwarzania dokumentów.
- Aktualizacji zapasów.
- Dużych importów przez API.
Ułatwia to również monitorowanie awarii i odzyskiwanie po nich.
8. Przechowuj informacje o ponowieniach w bazie danych
W aplikacji opartej na MariaDB prosta tabela zadań może wyglądać tak:
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
)
);
Proces roboczy wybiera zadania, w których:
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;
To tylko część selekcji w implementacji kolejki.
Jeśli kilka procesów roboczych może działać jednocześnie, zadania muszą być przejmowane atomowo, z użyciem odpowiedniej transakcji i strategii blokowania, aby zapobiec podwójnemu przetwarzaniu.
Proces roboczy powinien również stosować maksymalną liczbę ponowień i przenosić trwale zawodne zadania do stanu wymagającego zbadania.
W małej aplikacji takie podejście oparte na bazie danych może wystarczyć bez wprowadzania Redis lub dedykowanego brokera komunikatów.
9. Rejestruj awarie bez ujawniania danych wrażliwych
Przydatny dziennik API powinien odpowiadać na cztery pytania:
- Która operacja nie powiodła się?
- Która usługa zdalna była zaangażowana?
- Jaki był status HTTP lub błąd transportu?
- Kiedy aplikacja ponowi próbę?
Na przykład:
[2026-11-20 13:25:00 UTC]
service=inventory-api
operation=sync-products
status=429
attempt=2
next_retry=2026-11-20T13:26:00Z
Unikaj rejestrowania kluczy API, tokenów okaziciela, pełnych nagłówków autoryzacji, haseł lub niepotrzebnych danych osobowych.
Jeśli potrzebujesz korelować żądania, użyj wygenerowanego identyfikatora żądania.
Na przykład:
$requestId = bin2hex(random_bytes(8));
Możesz dołączyć ten identyfikator do dzienników aplikacji, a gdy jest to obsługiwane, wysłać go do zdalnego API.
10. Przetestuj strategię ponowień przed wdrożeniem produkcyjnym
Mechanizm ponowień należy przetestować w przewidywalnych scenariuszach awarii.
Nie musisz czekać na rzeczywistą awarię API.
Lokalny punkt końcowy testowy może celowo zwracać określone kody statusu.
Na przykład:
<?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',
]);
Uruchamiaj ten punkt końcowy tylko w lokalnym lub chronionym środowisku testowym.
Następnie sprawdź, czy klient:
- Wykrywa HTTP 429.
- Odczytuje nagłówek
Retry-After. - Czeka przed ponowieniem.
- Zatrzymuje się po skonfigurowanej liczbie prób.
- Zapisuje awarię bez ujawniania sekretów.
Powtórz test z HTTP 503 i celowo powolnym punktem końcowym.
Przetestuj także odpowiedź HTTP 400, aby potwierdzić, że klient nie ponawia trwałych błędów żądania.
Na koniec przetestuj operację, która mogła się powieść, zanim połączenie zostało przerwane. Jest to niezbędne w integracjach płatności i zamówień.
11. Lista kontrolna produkcyjna dla niezawodnych integracji API
Przed wdrożeniem integracji API sprawdź następujące elementy:
| Kontrola | Oczekiwane zachowanie |
|---|---|
| Limit czasu połączenia | Zdefiniowany i przetestowany |
| Całkowity limit czasu | Zdefiniowany i przetestowany |
| HTTP 429 | Respektuje limity szybkości |
| HTTP 5xx | Ponawia wybiórczo |
| HTTP 4xx | Brak ślepych ponowień |
| Limit ponowień | Zapobiega nieskończonym pętlom |
| Opóźnienie ponowienia | Backoff z jitterem |
| Operacje POST | Idempotentność lub uzgodnienie |
| Długie okresy oczekiwania | Odroczone do procesu roboczego |
| Dzienniki | Przydatne, prywatne, oczyszczone |
| Współbieżność procesów roboczych | Zapobieganie podwójnemu wykonaniu |
| Trwałe awarie | Widoczne i możliwe do odzyskania |
Podsumowanie: niezawodne API wymagają kontrolowanej obsługi awarii
Zewnętrzne API nigdy nie są idealnie dostępne.
Nawet dobrze utrzymywana usługa może doświadczyć tymczasowego przeciążenia, przerw w sieci lub ograniczenia szybkości.
Celem nie jest wyeliminowanie każdej awarii. Chodzi o to, aby aplikacja reagowała przewidywalnie, gdy awarie wystąpią.
Zacznij od rozsądnych limitów czasu i jawnej obsługi błędów HTTP. Dodaj ograniczone ponawianie z wykładniczym backoffem, respektuj opóźnienia ponowień podawane przez serwer i unikaj automatycznego powtarzania operacji, które mogłyby tworzyć zduplikowane dane.
W przypadku bardziej złożonych integracji przenieś ponawianie do trwałej kolejki zadań, zamiast utrzymywać otwarte żądania internetowe.
Te zasady mają zastosowanie do niemal każdej nowoczesnej aplikacji PHP, niezależnie od tego, czy tworzysz rozszerzenie CMS, synchronizujesz katalog e-commerce, wysyłasz e-maile transakcyjne czy integrujesz usługę płatności.
Niezawodny klient API to taki, który wie nie tylko, jak wysłać żądanie, ale także kiedy ponowić próbę, kiedy poczekać i kiedy przestać.