Come gestire i timeout delle API, i limiti di velocità e i tentativi di nuovo in PHP
Impara a costruire integrazioni API PHP affidabili con timeout di connessione, gestione degli errori HTTP, backoff esponenziale, supporto Retry-After e strategie di retry sicure.
Come gestire timeout, limiti di frequenza e tentativi delle API in PHP
Un'integrazione API funziona perfettamente durante lo sviluppo. Poi, un giorno, il tuo task pianificato si ferma a metà. Un servizio remoto risponde con HTTP 429, una connessione scade, o un errore HTTP 503 interrompe una sincronizzazione.
La tentazione è di ripetere immediatamente la richiesta.
Ma ripetere senza una strategia può peggiorare il problema. Può sovraccaricare un'API già in difficoltà, superare i limiti di frequenza o creare accidentalmente ordini e pagamenti duplicati.
Un client API affidabile richiede più di una chiamata curl_exec() riuscita.
In questo tutorial, costruiremo un client HTTP PHP pratico che gestisce timeout di connessione, errori HTTP, limiti di frequenza e fallimenti temporanei. Spiegheremo anche quando ripetere è sicuro, quando non lo è e come diagnosticare i problemi in produzione.
Gli esempi utilizzano l'estensione cURL integrata in PHP, senza Composer o dipendenze di terze parti.
1. Comprendere i diversi tipi di errori API
Non ogni richiesta non riuscita dovrebbe essere gestita allo stesso modo.
| Fallimento | Causa tipica | Azione consigliata |
|---|---|---|
| Timeout di connessione | Server irraggiungibile o connessione lenta | Ripetere con cautela |
| HTTP 400 | Parametri di richiesta non validi | Correggere la richiesta |
| HTTP 401 | Credenziali non valide o scadute | Controllare l'autenticazione |
| HTTP 404 | Risorsa non trovata | Controllare l'identificatore della risorsa |
| HTTP 429 | Limite di frequenza API superato | Rispettare Retry-After |
| HTTP 500 | Errore interno del server | Ripetere selettivamente |
| HTTP 503 | Temporanea indisponibilità del servizio | Ripetere con ritardo |
| JSON non valido | Formato di risposta imprevisto | Registrare ed investigare |
Un errore di rete è diverso anche da un errore HTTP.
Quando un'API restituisce HTTP 500, la richiesta HTTP è stata completata e il server ha restituito una risposta di errore.
Quando cURL segnala un fallimento di connessione, l'applicazione potrebbe non aver ricevuto alcuna risposta HTTP.
Questa distinzione è importante quando si decide se ripetere.
2. Configurare sempre timeout di connessione e richiesta
L'estensione cURL di PHP fornisce due impostazioni particolarmente utili:
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,
CURLOPT_CONNECTTIMEOUT limita la fase di connessione, mentre CURLOPT_TIMEOUT limita la durata complessiva del trasferimento. Entrambi sono documentati nel riferimento ufficiale cURL di PHP.
Senza limiti appropriati, un servizio esterno lento può occupare i worker PHP per molto più tempo del previsto.
Un punto di partenza pratico per un'API JSON convenzionale potrebbe essere di cinque secondi per l'instaurazione della connessione e quindici secondi per l'intera richiesta.
Questi non sono valori universali. Un caricamento di file o una generazione di report di lunga durata potrebbero richiedere una politica di timeout diversa.
Effettua la tua prima richiesta 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;
Questo costituisce una base utile, ma non gestisce ancora limiti di frequenza o fallimenti ripetibili.
3. Comprendere HTTP 429 e Retry-After
HTTP 429 significa che il client ha inviato troppe richieste entro un periodo definito dal fornitore dell'API.
Alcune API impongono limiti al minuto, all'ora, per chiave API o per account.
Un server può rispondere con:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
L'intestazione Retry-After indica al client quanto tempo attendere prima di riprovare.
L'intestazione può contenere un numero di secondi o una data HTTP.
Per esempio:
Retry-After: 120
Oppure:
Retry-After: Wed, 25 Nov 2026 10:00:00 GMT
Un client ben educato dovrebbe rispettare questa istruzione invece di inviare ripetutamente richieste.
Se il server non fornisce un ritardo di ripetizione, l'applicazione ha bisogno di una strategia di fallback.
4. Usare il backoff esponenziale invece di tentativi immediati
Il backoff esponenziale aumenta il tempo di attesa dopo fallimenti successivi.
Per esempio:
| Tentativo | Ritardo di esempio |
|---|---|
| 1 | 1 secondo |
| 2 | 2 secondi |
| 3 | 4 secondi |
| 4 | 8 secondi |
Invece di riprovare ogni secondo, l'applicazione attende progressivamente più a lungo.
Aggiungere una piccola variazione casuale, chiamata jitter, aiuta a impedire che molti client riprovino contemporaneamente.
Ecco una funzione di ritardo riutilizzabile:
<?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
);
}
Questo utilizza il jitter completo: il ritardo effettivo viene selezionato casualmente tra zero e il limite esponenziale.
Il ritardo casuale riduce le esplosioni sincronizzate di tentativi, sebbene non sostituisca un'istruzione Retry-After fornita esplicitamente dal server.

5. Costruire un client API PHP riutilizzabile
Combiniamo i concetti precedenti in un'implementazione funzionante.
Il nostro client:
- Impostare timeout di connessione e richieste complessive.
- Restituire lo stato HTTP e il corpo della risposta.
- Rilevare fallimenti di trasporto.
- Ripetere i fallimenti temporanei selezionati.
- Rispettare
Retry-Afterquando presente. - Limitare il numero di tentativi.
- Evitare di ripetere automaticamente operazioni non idempotenti.
<?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.'
);
}
Come usarlo
<?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());
}
Questa implementazione è intenzionalmente limitata alle richieste GET verso endpoint API attendibili.
Non ripete automaticamente le operazioni POST, PUT, PATCH o DELETE, perché queste richiedono salvaguardie aggiuntive.
Restituisce inoltre al chiamante le risposte HTTP non ripetibili, che deve decidere come gestire.
Per i sistemi di produzione, dovresti inoltre validare i tipi di risposta, imporre limiti di dimensione delle risposte e distinguere errori di trasporto ripetibili da fallimenti permanenti di TLS o configurazione.
6. Perché ripetere le richieste POST può essere pericoloso
Immagina un'applicazione e-commerce che invia questa richiesta:
POST /api/orders
Content-Type: application/json
{
"product_id": 42,
"quantity": 1
}
L'API remota crea l'ordine, ma la connessione cade prima che l'applicazione riceva la risposta.
L'applicazione vede un timeout.
L'ordine è fallito?
Non necessariamente. L'ordine potrebbe già esistere.
Se l'applicazione riprova immediatamente, potrebbe creare un secondo ordine.
Ecco perché un timeout non dimostra che un'operazione è fallita sul server.
Usa chiavi di idempotenza quando supportate
Alcune API supportano chiavi di idempotenza.
Per esempio:
Idempotency-Key: order-8f7a2c
Quando l'API fornisce un meccanismo di idempotenza documentato, riutilizzare la stessa chiave per i tentativi della stessa operazione logica può prevenire l'elaborazione duplicata.
Ma questo comportamento è specifico dell'API. Aggiungere un'intestazione Idempotency-Key non rende automaticamente idempotente un'API arbitraria.
Per operazioni che coinvolgono pagamenti, ordini, abbonamenti o modifiche al database, seguire la documentazione ufficiale del fornitore su ripetimenti e idempotenza.
Quando non esiste un meccanismo di idempotenza, potresti dover interrogare lo stato dell'operazione o riconciliare i risultati prima di tentare di nuovo.
7. Evitare sleep all'interno di richieste web di lunga durata

Il nostro esempio utilizza usleep() per rendere il comportamento di ripetizione facile da capire.
Ciò può essere accettabile per operazioni brevi con un budget di ripetizione strettamente controllato.
Tuttavia, un sito web di produzione non dovrebbe tenere occupati i worker PHP per minuti mentre attende un'API esterna.
Supponiamo che un'API risponda con:
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Attendere un'ora all'interno di una richiesta HTTP sarebbe una scelta di progettazione scadente.
Una soluzione migliore è differire l'operazione.
Per esempio, memorizza un lavoro in sospeso:
Job ID: 1842
Status: pending
Attempts: 2
Next attempt: 2026-11-20 14:30:00 UTC
Un worker pianificato può quindi elaborare il lavoro quando diventa idoneo.
Questo approccio è particolarmente utile per:
- Sincronizzazione del catalogo prodotti.
- Consegna email.
- Pubblicazione sui social media.
- Elaborazione documenti.
- Aggiornamento inventario.
- Importazioni API di grandi dimensioni.
Rende inoltre i fallimenti più facili da monitorare e recuperare.
8. Memorizzare le informazioni di ripetizione in un database
Per un'applicazione basata su MariaDB, una semplice tabella dei lavori potrebbe essere così:
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
)
);
Il worker seleziona i lavori dove:
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;
Questa è solo la parte di selezione di un'implementazione di coda.
Se più worker possono essere eseguiti simultaneamente, i lavori devono essere reclamati in modo atomico, utilizzando una transazione e una strategia di blocco appropriate, per prevenire l'elaborazione duplicata.
Il worker dovrebbe anche applicare un conteggio massimo di ripetizioni e spostare i lavori che falliscono permanentemente in uno stato che richiede indagine.
Per una piccola applicazione, questo approccio basato su database può essere sufficiente senza introdurre Redis o un message broker dedicato.
9. Registrare i fallimenti senza esporre dati sensibili
Un registro API utile dovrebbe rispondere a quattro domande:
- Quale operazione è fallita?
- Quale servizio remoto è stato coinvolto?
- Qual è stato lo stato HTTP o l'errore di trasporto?
- Quando l'applicazione ripeterà?
Per esempio:
[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 di registrare chiavi API, token bearer, intestazioni di autorizzazione complete, password o informazioni personali non necessarie.
Se devi correlare le richieste, usa un identificatore di richiesta generato.
Per esempio:
$requestId = bin2hex(random_bytes(8));
Puoi includere questo identificatore nei log dell'applicazione e, quando supportato, inviarlo all'API remota.
10. Testa la tua strategia di ripetizione prima della produzione
Un meccanismo di ripetizione dovrebbe essere testato contro scenari di fallimento prevedibili.
Non devi aspettare un'interruzione reale dell'API.
Un endpoint di test locale può restituire deliberatamente codici di stato specifici.
Per esempio:
<?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',
]);
Esegui questo endpoint solo in un ambiente di test locale o protetto.
Poi verifica che il tuo client:
- Rileva HTTP 429.
- Legge l'intestazione
Retry-After. - Attende prima di ripetere.
- Si ferma dopo il numero configurato di tentativi.
- Registra il fallimento senza esporre segreti.
Ripeti con HTTP 503 e un endpoint deliberatamente lento.
Testa anche una risposta HTTP 400 per confermare che il client non ripeta errori di richiesta permanenti.
Infine, testa un'operazione che potrebbe essere riuscita prima che la connessione fallisse. Ciò è essenziale per le integrazioni di pagamento e ordine.
11. Una checklist di produzione per integrazioni API affidabili
Prima di distribuire un'integrazione API, verifica quanto segue:
| Controllo | Comportamento atteso |
|---|---|
| Timeout di connessione | Definito e testato |
| Timeout complessivo | Definito e testato |
| HTTP 429 | Rispetta i limiti di frequenza |
| HTTP 5xx | Ripete selettivamente |
| HTTP 4xx | Nessun ripetimento cieco |
| Limite di ripetizione | Previene loop infiniti |
| Ritardo di ripetizione | Backoff con jitter |
| Operazioni POST | Idempotenza o riconciliazione |
| Lunghi periodi di attesa | Differiti a un worker |
| Log | Utili, privati, sanificati |
| Concorrenza worker | Esecuzione duplicata prevenuta |
| Fallimenti permanenti | Visibili e recuperabili |
Conclusione: le API affidabili richiedono una gestione controllata dei fallimenti
Le API esterne non sono mai perfettamente disponibili.
Anche un servizio ben mantenuto può sperimentare sovraccarico temporaneo, interruzioni di rete o limitazione della frequenza.
L'obiettivo non è eliminare ogni fallimento. È far sì che la tua applicazione risponda in modo prevedibile quando si verificano fallimenti.
Inizia con timeout ragionevoli e una gestione esplicita degli errori HTTP. Aggiungi ripetimenti limitati con backoff esponenziale, rispetta i ritardi di ripetizione forniti dal server ed evita di ripetere automaticamente operazioni che potrebbero creare dati duplicati.
Per integrazioni più complesse, sposta i ripetimenti in una coda di lavori persistente invece di mantenere aperte le richieste web.
Questi principi si applicano quasi a ogni applicazione PHP moderna, sia che tu stia costruendo un'estensione CMS, sincronizzando un catalogo e-commerce, inviando email transazionali o integrando un servizio di pagamento.
Un client API affidabile è uno che sa non solo come inviare una richiesta, ma anche quando ripetere, quando attendere e quando fermarsi.