Web și dezvoltare

Cum să gestionați întârzierile API, limitele de rată și reîncercările în PHP

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

Învață cum să construiești integrații API PHP fiabile cu întârzieri de conexiune, gestionarea erorilor HTTP, backoff exponențial, suport pentru Retry-After și strategii sigure de reîncercare.

Cum se Gestionează Timpouturile API, Limita de Cuvânt și Repornirile în PHP

O integrare API funcționează perfect în timpul dezvoltării. Apoi, o zi, sarcina programată se oprește pe mijloc. Un serviciu de la distanță răspunde cu HTTP 429, o conexiune expiră sau o eroare HTTP 503 întrerupe o sincronizare.

Tentarea este să repornești imediat cererea.

Dar repornirea fără o strategie poate înrăutăți problema. Poate încărca un API deja suferințând, depăși limitele de rate sau, din păcate, crea comenzi și plăți duplicate.

Un client API fiabil are nevoie de mai mult decât o apelare curl_exec() de succes.

În acest tutorial, vom construi un client HTTP PHP practic care gestionează timpouturile de conexiune, erorile HTTP, limitele de rate și eșecurile temporare. Vom explica și când repornirea este sigură, când nu este, și cum se diagnostică problemele în producție.

Exemplele folosesc extensia cURL built-in a PHP, fără Composer sau dependențe de la terțe.

1. Înțelegeți diferitele tipuri de eșecuri API

Nu fiecare cerere nereușită trebuie tratată la fel.

Eșec Cauza tipică Acțiune recomandată
Timp de conexiune expirat Server indisponibil sau conexiune lentă Repornește cu prudență
HTTP 400 Parametri de cerere invalidi Corectați cererea
HTTP 401 Credențiale invalide sau expirate Verificați autentificarea
HTTP 404 Resursa nu a fost găsită Verificați identificatorul resursei
HTTP 429 Limita de rate API depășită Respectați Retry-After
HTTP 500 Eroare internă de server Repornește selectiv
HTTP 503 Indisponibilitate temporară a serviciului Repornește cu oște
JSON invalid Format de răspuns neașteptat Logați și investigați

O eroare de rețea este și diferită de la o eroare HTTP.

Când un API returnează HTTP 500, cererea HTTP a fost completată și serverul a returnat un răspuns de eroare.

Când cURL raportează o eroare de conexiune, aplicația dvs. s-ar putea să nu fi primit deloc un răspuns HTTP.

Această diferență contează atunci când se decide dacă se repornește.

2. Configurați mereu timpurile de conexiune și de cerere

PHP cURL oferă două setări particularmente utile:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT limitează fazăa de conexiune, în timp ce CURLOPT_TIMEOUT limitează durata totală a transferului. Ambele sunt documentate în oficialul manual PHP pentru cURL.

Fără limite potrivite, un serviciu extern lent poate ocupa worker-ele PHP mult mai mult decât se aștepta.

Un punct de plecare practic pentru o API JSON obișnuit ar putea fi cinci secunde pentru stabilirea conexiunii și douăsprezece secunde pentru cererea completă.

Aceste valori nu sunt universale. Încărcarea unui fișier sau generarea unui raport care rulează mult timp poate necesita o politică de timeout diferită.

Faceți prima cerere 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;

Această creează o fundație utilă, dar nu abordează încă limitele de rate sau eșecurile reintreribile.

3. Înțelegeți HTTP 429 și Retry-After

HTTP 429 înseamnă că clientul a trimis prea multe cereri într-un interval definit de furnizorul API.

Unele API impun limite per minut, per oră, per cheie API sau per cont.

Serverul poate răspunde cu:

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

Header-ul Retry-After înseamnă clientului cât ar trebui să aștepte înainte de a reporni.

Header-ul poate conține sau un număr de secunde sau o dată HTTP.

De exemplu:

Retry-After: 120

Sau:

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

Un client bine comportat ar trebui să respecte această instrucțiune, în loc să trimita repetat cereri.

Dacă serverul nu oferă un interval de repornire, aplicația dvs. are nevoie de o strategie de rezervă.

4. Folosiți backoff exponențial în loc de reporniri imediate

Backoff exponențial mărește timpul de așteptare după eșecuri succesive.

De exemplu:

Repro Orez de exemplu
1 1 secundă
2 2 secunde
3 4 secunde
4 8 secunde

În loc să repornească la fiecare secundă, aplicația așteaptă progresiv mai mult.

Adăugarea unei mici variații aleatorii, numită jitter, ajută la prevenirea multor clienți de a reporni simultan.

Iată o funcție de amortizare reutilizabilă:

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

Aceasta folosește jitter complet: timpul real de așteptare este selectat aleatoriu între zero și limita exponențială.

Timpul aleatoriu de la reduc sincronizate de reporniri, deși nu înlocuiește o instrucțiune explicită de la server pentru Retry-After.

Illustration of the article's main concept

5. Construiți un client API PHP reutilizabil

Să combinăm conceptele anterioare într-o implementare funcțională.

Clientul nostru va:

  • Set timpurile de conexiune și de cerere.
  • Returnați starea HTTP și corpul răspunsului.
  • Detectați eșecurile de transport.
  • Repornește selectiv eșecurile temporare.
  • Respectați Retry-After atunci când este prezent.
  • Limitați numărul de încercări.
  • Evitați repornirea automată a operațiilor ne-idempotente.
<?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.'
    );
}

Cum se folosește

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

Această implementare este intenționat limitată la cereri GET pentru endpoint-uri API de încredere.

Nu repornește automat cererile POST, PUT, PATCH sau DELETE, deoarece acestea necesită măsuri suplimentare de protecție.

De asemenea, returnează răspunsurile HTTP non-reintreribile apelatorului, care trebuie să decidă cum să le gestioneze.

Pentru sisteme de producție, ar trebui să validați tipurile de răspuns, să aplicați limite de dimensiune a răspunsului și să distingeți erorile de transport reintreribile de la erorile permanente de TLS sau de configurare.

6. De ce repornirea cererilor POST poate fi periculoasă

Imagineți o aplicație de ecommerce care trimite această cerere:

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

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

API-ul de la distanță creează comanda, dar conexiunea se întrerupe înainte ca aplicația dvs. să primească răspunsul.

Aplicația dvs. vede un timp de așteptare expirat.

Comanda a eşuat?

Nu neapărat. Comanda poate exista deja.

Dacă aplicația dvs. repornește imediat, ar putea crea o a doua comandă.

Acesta este motivul pentru care un timp de așteptare nu dovedește că o operațiune a eşuat pe server.

Utilizați chei de idempotență atunci când este suportat

Unele API suportă chei de idempotență.

De exemplu:

Idempotency-Key: order-8f7a2c

Când API-ul oferă un mecanism documentat de idempotență, reutilizarea aceluiași chei pentru repornirile acelei aceleasi operații logice poate preveni procesarea de duplicate.

Dar acest comportament este specific API-ului. Adăugarea unui antet Idempotency-Key nu face automat o orice API idempotent.

Pentru operațiile care implică plăți, comenzi, abonamente sau modificări în baza de date, urmați documentația oficială de retry și idempotență a furnizorului.

Când nu există un mecanism de idempotență, poate fi necesar să interogați starea operațiunii sau să reconciliați rezultatele înainte de a o încerca din nou.

7. Evitați să dormiți în interiorul cererilor web lungi

Technical workflow illustration

Exemplul nostru folosește usleep() pentru a face comportamentul de retry ușor de înțeles.

Acesta poate fi acceptabil pentru operațiii scurte cu un buget de retry strict controlat.

Cu însă, un site web de producție nu ar trebui să țină ocupate worker-ele PHP pentru minute în timpul așteptării unei API externe.

Sposează că o API răspunde cu:

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

Aștepta o oră într-o cerere HTTP ar fi o designare proastă.

O soluție mai bună este să amânăm operațiunea.

De exemplu, stocați o sarcină în așteptare:

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

Un worker programat poate apoi procesa sarcina atunci când devine eligibil.

Această abordare este deosebit de utilă pentru:

  • Sincronizarea catalogului de produse.
  • Livrare emailuri.
  • Publicare pe social media.
  • Procesarea documentelor.
  • Actualizări de inventar.
  • Importuri API de mari dimensiuni.

Face falutele mai ușor de monitorat și recuperat.

8. Stocați informațiile despre retry într-o bază de date

Pentru o aplicație bazată pe MariaDB, o tabelă simplă de sarcini ar putea arăta astfel:

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-ul selectează sarcini unde:

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;

Aceasta este doar partea de selectare a unei implementări de coadă.

Dacă mai multe workeri pot rula simultan, sarcinile trebuie câștigate atomic, folosind o strategie transacțională și de blocare adecvată, pentru a preveni procesarea de duplicate.

Worker-ul ar trebui să aplici un număr maxim de reporniri și să mută sarcinile care eșuează permanent într-un stare care necesită investigare.

Pentru o aplicație mică, această abordare bazată pe baza de date poate fi suficientă fără a introduce Redis sau un broker dedicat de mesaje.

9. Logați eșecurile fără a expunea date sensibile

Un log API util ar trebui să răspundă la patru întrebări:

  1. Care operație a eşuat?
  2. Care serviciu de la distanță a fost implicat?
  3. Care a fost starea HTTP sau eroarea de transport?
  4. Când va reporni aplicația?

De exemplu:

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

Evitați logarea cheilor API, tokenurilor de tip bearer, așezătorilor de autorizare, parolelor sau informațiilor personale inutile.

Dacă trebuie să corelați cererile, utilizați un identificator de cerere generat.

De exemplu:

$requestId = bin2hex(random_bytes(8));

Puteți include acest identificator în jurnalele aplicației și, atunci când este suportat, să îl trimiteți API-ului de la distanță.

10. Testați strategia de retry înainte de producție

Un mecanism de retry ar trebui testat împotriva scenariilor de eșec predictibile.

Nu trebuie să așteptați o reușită reală.

Un endpoint de test local poate returna intenționat anumite coduri de stare.

De exemplu:

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

Rulați acest endpoint doar în un mediu de test local sau protejat.

Apoi verificați că clientul dvs.:

  • Detectează HTTP 429.
  • Citește antetul Retry-After.
  • Așteaptă înainte de a reporni.
  • Se oprește după numărul de încercări configurat.
  • Înregistrează eșecul fără a expune secrete.

Repetați cu HTTP 503 și un endpoint intenționat de lent.

De asemenea, testați un răspuns HTTP 400 pentru a confirma că clientul nu repornește erorile permanente de cerere.

În final, testați o operațiune care ar putea să fi reușit înainte de că conexiunea să eşuiască. Acesta este esențial pentru integrările de plăți și comenzi.

11. O listă de verificare pentru integrări API fiabile

Înainte de a implementa o integrare API, verificați următoarele:

Verificare Comportament așteptat
Timp de conexiune expirat Definite și testate
Timp de așteptare total expirat Definite și testate
HTTP 429 Respectă limitele de rate
HTTP 5xx Repornește selectiv
HTTP 4xx Nu repornește nevăzate
Limita de retry Previne bucle nesfinte
Intervalul de retry Backoff cu jitter
Operațiile POST Idempotency sau reconciliere
Perioade lungi de așteptare Amânate unui worker
Jurnale Utile, private, sanitize
Concurența workerilor Execuția de duplicate prevenită
Eșecurile permanente Vizibile și recuperabile

Concluzie: API-urile fiabile necesită o gestionare controlată a eșecurilor

API-urile externe nu sunt niciodată perfect disponibile.

Chiar un serviciu bine întreținut poate experiența supraîncărcare temporară, interruptii de rețea sau limitare a ratei.

Scopul nu este să elimini fiecare eșec. Este să facă aplicația să răspundă predictabil când apare eșecurile.

Începeți cu timpuri sensate și o gestionare explicită a erorilor HTTP. Adăugați reporniri limitate cu backoff exponențial, respectați intervalele de retry furnizate de server și evitați repetarea automată a operațiilor care ar putea crea date duplicate.

Pentru integrări mai complexe, mutați repornirile într-o coadă persistentă de sarcini, în loc să țineți cererile web deschise.

Aceste principii se aplică aproape fiecărei aplicații PHP modernă, fie că construiești o extensie CMS, sincronizezi un catalog de ecommerce, trimiți emailuri transacționale sau integrezi un serviciu de plăți.

Un client API fiabil este unul care nu știe doar cum să trimită o cerere, ci și când să repornească, când să aștepte și când să se oprească.

Referințe oficiale