Web a vývoj

Jak řešit časové limity API, limity rychlosti a opakování v PHP

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

Naučte se, jak vytvářet spolehlivé PHP API integrace s časovými limity připojení, zpracováním chyb HTTP, exponenciálním zpomalováním, podporou Retry-After a bezpečnými strategiemi opakování.

Jak v PHP zvládat časové limity API, limity požadavků a opakované pokusy

Integrace API funguje během vývoje dokonale. Pak jednoho dne vaše naplánovaná úloha ustrne v polovině. Vzdálená služba odpoví s HTTP 429, spojení vyprší, nebo synchronizaci přeruší chyba HTTP 503.

Cuknem je požadavek okamžitě zopakovat.

Opakování bez strategie však může problém zhoršit. Může přetížit už tak zápasící API, překročit limity požadavků nebo nechtěně vytvořit duplicitní objednávky a platby.

Spolehlivý klient API potřebuje víc než úspěšné volání curl_exec().

V tomto tutoriálu vytvoříme praktický HTTP klient v PHP, který zvládne časové limity spojení, chyby HTTP, limity požadavků a dočasné výpadky. Vysvětlíme také, kdy je opakování bezpečné, kdy ne a jak diagnostikovat problémy v produkci.

Příklady používají vestavěné rozšíření cURL jazyka PHP, bez Composeru či závislostí třetích stran.

1. Pochopte různé typy výpadků API

Ne každou neúspěšnou žádost by se mělo zacházet stejným způsobem.

Výpadek Typická příčina Doporučená akce
Časový limit spojení Server nedosažitelný nebo pomalé spojení Opatrně zopakovat
HTTP 400 Neplatné parametry požadavku Opravit požadavek
HTTP 401 Neplatné nebo vypršelé pověření Zkontrolovat ověření
HTTP 404 Prostředek nenalezen Zkontrolovat identifikátor prostředku
HTTP 429 Překročen limit požadavků API Respektovat Retry-After
HTTP 500 Interní chyba serveru Selektivně zopakovat
HTTP 503 Dočasná nedostupnost služby Zopakovat s prodlevou
Neplatné JSON Neočekávaný formát odpovědi Zapsat do protokolu a prošetřit

Chyba sítě se také liší od chyby HTTP.

Když API vrátí HTTP 500, požadavek HTTP se dokončil a server vrátil chybovou odpověď.

Když cURL nahlásí selhání spojení, vaše aplikace možná vůbec neobdržela žádnou odpověď HTTP.

Tento rozdíl je důležitý při rozhodování, zda opakovat.

2. Vždy nastavte časové limity spojení a požadavku

cURL v PHP poskytuje dvě obzvlášť užitečná nastavení:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT omezuje fázi spojení, zatímco CURLOPT_TIMEOUT omezuje celkovou dobu přenosu. Obě jsou zdokumentována v oficiální referenci cURL jazyka PHP.

Bez vhodných limitů může pomalá externí služba zaměstnat PHP workery na mnohem delší dobu, než se očekává.

Praktickým výchozím bodem pro konvenční JSON API může být pět sekund pro navázání spojení a patnáct sekund pro celý požadavek.

Nejde o univerzální hodnoty. Nahrávání souboru nebo generování dlouhého reportu může vyžadovat jinou politiku časových limitů.

Vytvořte svůj první požadavek na 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;

Toto vytvoří užitečný základ, ale dosud nezpracovává limity požadavků ani opakovatelné výpadky.

3. Pochopte HTTP 429 a Retry-After

HTTP 429 znamená, že klient odeslal příliš mnoho požadavků během období definovaného poskytovatelem API.

Některá API stanovují limity za minutu, za hodinu, na klíč API nebo na účet.

Server může odpovědět s:

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

Hlavička Retry-After sděluje klientovi, jak dlouho by měl počkat, než to zkusí znovu.

Hlavička může obsahovat buď počet sekund, nebo datum HTTP.

Například:

Retry-After: 120

Nebo:

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

Dobře vychovaný klient by měl tento pokyn respektovat, místo aby opakovaně odesílal požadavky.

Pokud server neposkytne prodlevu před opakováním, vaše aplikace potřebuje náhradní strategii.

4. Používejte exponenciální oddálení místo okamžitých opakování

Exponenciální oddálení zvyšuje čekací dobu po successive výpadcích.

Například:

Opakování Příklad prodlevy
1 1 sekunda
2 2 sekundy
3 4 sekundy
4 8 sekund

Místo opakování každou sekundu aplikace čeká postupně déle.

Přidání malé náhodné odchylky, nazývané jitter, pomáhá zabránit tomu, aby mnoho klientů opakovalo současně.

Zde je znovupoužitelná funkce prodlevy:

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

Toto používá plný jitter: skutečná prodleva je náhodně vybrána mezi nulou a exponenciálním stropem.

Náhodná prodleva snižuje synchronizované výbuchy opakování, ačkoli nenahrazuje výslovný pokyn Retry-After poskytnutý serverem.

Illustration of the article's main concept

5. Vytvořte znovupoužitelný klient PHP API

Spojme předchozí koncepty do funkční implementace.

Náš klient bude:

  • Nastavovat časové limity spojení a celkového požadavku.
  • Vracet stav HTTP a tělo odpovědi.
  • Detekovat chyby přenosu.
  • Opakovat vybrané dočasné výpadky.
  • Respektovat Retry-After, je-li přítomen.
  • Omezovat počet pokusů.
  • Nevyvarovat se automatického opakování neidempotentních operací.
<?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 ji používat

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

Tato implementace je záměrně omezena na požadavky GET proti důvěryhodným koncovým bodům API.

Neopakuje automaticky operace POST, PUT, PATCH ani DELETE, protože ty vyžadují další záruky.

Také vrací neopakovatelné odpovědi HTTP volajícímu, který musí rozhodnout, jak je zpracovat.

Pro produkční systémy byste měli navíc validovat typy odpovědí, vynucovat limity velikosti odpovědi a odlišovat opakovatelné chyby přenosu od trvalých selhání TLS či konfigurace.

6. Proč může být opakování požadavků POST nebezpečné

Představte si aplikaci e-shopu, která odesílá tento požadavek:

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

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

Vzdálené API vytvoří objednávku, ale spojení se přeruší, než vaše aplikace obdrží odpověď.

Vaše aplikace vidí vypršení časového limitu.

Selhala objednávka?

Ne nutně. Objednávka již může existovat.

Pokud vaše aplikace okamžitě zopakuje, mohla by vytvořit druhou objednávku.

To je důvod, proč vypršení časového limitu nedokazuje, že operace na serveru selhala.

Používejte klíče idempotence, jsou-li podporovány

Některá API podporují klíče idempotence.

Například:

Idempotency-Key: order-8f7a2c

Když API poskytuje zdokumentovaný mechanismus idempotence, opakované použití stejného klíče pro opakování téže logické operace může zabránit duplicitnímu zpracování.

Toto chování je však specifické pro dané API. Přidání hlavičky Idempotency-Key nedělá z libovolného API idempotentní automaticky.

U operací zahrnujících platby, objednávky, předplatná nebo úpravy databáze se řiďte oficiální dokumentací poskytovatele o opakování a idempotenci.

Když žádný mechanismus idempotence neexistuje, možná budete muset před dalším pokusem dotázat stav operace nebo vyrovnat výsledky.

7. Vyhněte se uspávání uvnitř dlouho běžících webových požadavků

Technical workflow illustration

Náš příklad používá usleep(), aby bylo chování při opakování snadno pochopitelné.

To může být přijatelné pro krátké operace s těsně řízeným rozpočtem opakování.

Produkční webová stránka by však neměla držet PHP workery zaměstnané celé minuty, zatímco čeká na externí API.

Předpokládejme, že API odpoví s:

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

Čekání jednu hodinu uvnitř požadavku HTTP by bylo špatným návrhem.

Lepším řešením je operaci odložit.

Například uložte čekající úlohu:

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

Naplánovaný worker pak může úlohu zpracovat, jakmile se stane způsobilou.

Tento přístup je obzvlášť užitečný pro:

  • Synchronizaci produktového katalogu.
  • Doručování e-mailů.
  • Publikování na sociálních sítích.
  • Zpracování dokumentů.
  • Aktualizace skladových zásob.
  • Velké importy API.

Také usnadňuje monitorování a obnovu po výpadcích.

8. Ukládejte informace o opakování do databáze

Pro aplikaci podloženou MariaDB by jednoduchá tabulka úloh mohla vypadat takto:

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

Worker vybírá úlohy, kde:

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;

Toto je pouze výběrová část implementace fronty.

Pokud může současně běžet několik workerů, úlohy musí být nárokovány atomicky, pomocí vhodné strategie transakcí a zamykání, aby se zabránilo duplicitnímu zpracování.

Worker by měl také uplatnit maximální počet opakování a přesunout trvale selhávající úlohy do stavu vyžadujícího prošetření.

Pro malou aplikaci může být tento přístup podložený databází postačující, aniž by bylo nutné zavádět Redis nebo dedikovaný broker zpráv.

9. Protokolujte výpadky bez odhalování citlivých údajů

Užitečný protokol API by měl odpovědět na čtyři otázky:

  1. Která operace selhala?
  2. Které vzdálené služby se to týkalo?
  3. Jaký byl stav HTTP nebo chyba přenosu?
  4. Kdy aplikace zopakuje?

Například:

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

Vyhněte se protokolování klíčů API, bearer tokenů, celých autorizačních hlaviček, hesel nebo zbytečných osobních údajů.

Pokud potřebujete korelovat požadavky, použijte vygenerovaný identifikátor požadavku.

Například:

$requestId = bin2hex(random_bytes(8));

Tento identifikátor můžete zahrnout do protokolů aplikace a, je-li podporován, odeslat jej vzdálenému API.

10. Otestujte svou strategii opakování před produkcí

Mechanismus opakování by měl být testován proti předvídatelným scénářům výpadků.

Nemusíte čekat na skutečný výpadek API.

Místní testovací koncový bod může záměrně vracet konkrétní stavové kódy.

Například:

<?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',
]);

Spouštějte tento koncový bod pouze v místním nebo chráněném testovacím prostředí.

Poté ověřte, že váš klient:

  • Detekuje HTTP 429.
  • Přečte hlavičku Retry-After.
  • Počká před opakováním.
  • Zastaví se po nakonfigurovaném počtu pokusů.
  • Zaznamená výpadek bez odhalení tajemství.

Zopakujte s HTTP 503 a záměrně pomalým koncovým bodem.

Také otestujte odpověď HTTP 400, abyste potvrdili, že klient neopakuje trvalé chyby požadavku.

Nakonec otestujte operaci, která mohla uspět před selháním spojení. To je zásadní pro integrace plateb a objednávek.

11. Produkční kontrolní seznam pro spolehlivé integrace API

Před nasazením integrace API ověřte následující:

Kontrola Očekávané chování
Časový limit spojení Definován a otestován
Celkový časový limit Definován a otestován
HTTP 429 Respektuje limity požadavků
HTTP 5xx Selektivně opakuje
HTTP 4xx Žádné slepé opakování
Limit opakování Zabraňuje nekonečným smyčkám
Prodleva opakování Oddálení s jitterem
Operace POST Idempotence nebo vyrovnání
Dlouhé čekací doby Odloženo na workera
Protokoly Užitečné, soukromé, očištěné
Souběžnost workerů Duplicitní provedení zabráněno
Trvalé výpadky Viditelné a obnovitelné

Závěr: spolehlivá API vyžadují řízené zpracování výpadků

Externí API nejsou nikdy dokonale dostupná.

Dokonce i dobře udržovaná služba může zaznamenat dočasné přetížení, přerušení sítě nebo omezení požadavků.

Cílem není odstranit každý výpadek. Jde o to, aby vaše aplikace reagovala předvídatelně, když výpadky nastanou.

Začněte rozumnými časovými limity a explicitním zpracováním chyb HTTP. Přidejte omezená opakování s exponenciálním oddálením, respektujte prodlevy před opakováním poskytnuté serverem a vyhněte se automatickému opakování operací, které by mohly vytvořit duplicitní data.

Pro složitější integrace přesuňte opakování do perzistentní fronty úloh místo toho, abyste drželi webové požadavky otevřené.

Tyto principy platí pro téměř každou moderní aplikaci v PHP, ať už vytváříte rozšíření CMS, synchronizujete katalog e-shopu, odesíláte transakční e-maily nebo integrujete platební službu.

Spolehlivý klient API je ten, který ví nejen, jak odeslat požadavek, ale také kdy opakovat, kdy počkat a kdy přestat.

Oficiální reference