Pattern di retry e rate limit per le API dei marketplace

Le API dei marketplace impongono limiti di chiamata e restituiscono, prima o poi, errori temporanei. Un'integrazione affidabile non li subisce: li gestisce con pattern consolidati di retry e rate limiting. Vediamo i principali.

Distinguere gli errori

Non tutti gli errori vanno ritentati. La prima regola è classificarli:

Tipo	Esempio	Azione
Transitorio	429, 503, timeout	Retry con backoff
Permanente	400, 422 (dato non valido)	Non ritentare, correggere
Autenticazione	401	Rinnovare token, poi retry

Backoff esponenziale con jitter

Ritentare subito peggiora le cose. Il pattern corretto è il backoff esponenziale (1s, 2s, 4s, 8s…) con un jitter casuale per evitare che molti client ritentino in sincrono. Va sempre rispettato l'header Retry-After quando l'API lo fornisce.

Rispettare i limiti: token bucket

Per non superare i limiti in partenza si usa un rate limiter lato client, tipicamente un token bucket: i token si ricaricano a ritmo costante e ogni chiamata ne consuma uno. Quando i token finiscono, le chiamate aspettano. Con più worker, il limiter va condiviso (es. tramite uno store centrale) per rispettare un budget globale.

Circuit breaker

Se un'API è chiaramente in difficoltà, continuare a chiamarla è dannoso. Il circuit breaker "apre" il circuito dopo una soglia di errori, blocca temporaneamente le chiamate e poi prova a richiuderlo gradualmente. Protegge sia il fornitore sia la propria pipeline.

Idempotenza: la rete di sicurezza

Retry e idempotenza vanno insieme. Se un'operazione viene ritentata, deve poter essere ripetuta senza creare duplicati: chiavi idempotenti, controlli di esistenza, upsert. Senza idempotenza, i retry diventano una fonte di errori invece che una soluzione.

Mettere tutto insieme

In pratica le chiamate passano per una catena: rate limiter (non superare il budget) → circuit breaker (non insistere su un servizio rotto) → retry con backoff (assorbire i transitori) → idempotenza (rendere sicuro il retry). Su Azure questi pattern si implementano nei worker e si combinano con code e dead-letter per i fallimenti definitivi.

Errori comuni

• ritentare ogni errore, anche quelli permanenti;
• retry immediati senza backoff né jitter;
• ignorare Retry-After e i limiti dichiarati;
• retry senza idempotenza, che generano duplicati.

Conclusione

Backoff con jitter, token bucket, circuit breaker e idempotenza sono i quattro pilastri della resilienza verso le API con limiti. Applicati insieme, trasformano errori inevitabili in eventi gestiti, mantenendo la pipeline stabile anche sotto pressione.