GoCardless 429 rate_limit_exceeded: troppe richieste al minuto

Cosa dice GoCardless

La pagina dei limiti di GoCardless indica la cifra: 1.600 richieste al minuto in un'integrazione standard e 1.600 al minuto per merchant in un'integrazione partner. Quando il limite viene superato, l'API restituisce il 429, e GoCardless precisa che queste richieste si possono ripetere senza problemi: «These requests are safe to retry.». Per sapere quando, rimanda alle intestazioni della risposta: ratelimit-limit, ratelimit-remaining e ratelimit-reset.

Da dove arrivano tante richieste

Il limite conta tutte le richieste all'API, non solo quelle che creano addebiti. Con il connettore, ogni addebito con un mandato salvato è una richiesta, che provenga da un abbonamento che si rinnova o da un pagamento registrato con il metodo di pagamento del cliente. Ogni evento di un pagamento che arriva in Odoo è un'altra richiesta, perché il connettore non si fida solo della notifica: chiede a GoCardless quel pagamento e applica lo stato che gli restituisce. Un lotto grande nello stesso momento, come molti rinnovi insieme mentre arrivano gli eventi degli addebiti precedenti, somma entrambe le cose.

GoCardless classifica questo reason tra gli errori invalid_api_usage, quelli che dipendono da come viene fatta la richiesta, e per questi chiede di avvisare il team tecnico («alert your dev team»). Un 429 isolato non lo richiede; uno che si ripete ogni giorno, sì.

Cosa fa il connettore

1. Legge l'intestazione ratelimit-reset e calcola quanto manca: l'ora indicata meno quella del server di Odoo.
2. Attende quel tempo, come minimo 1 secondo e come massimo 65. Se l'intestazione manca o non si può leggere, attende 1 secondo. Il limite serve a evitare che un orologio sbagliato blocchi il processo di Odoo che aspetta.
3. Ripete la richiesta una sola volta.
4. Se la ripetizione riceve di nuovo un 429, non attende oltre: lo tratta come qualsiasi altro rifiuto dell'API.

Il connettore non conta le proprie richieste né le frena in anticipo. Non legge ratelimit-remaining: attende solo quando GoCardless ha già risposto 429.

Se anche il secondo tentativo incontra il limite

Dipende da cosa stava facendo Odoo in quel momento.

• Se era un addebito, la transazione passa a «Errore» con «GoCardless rejected the request.» e, sotto, il messaggio di GoCardless con rate_limit_exceeded e il request_id tra parentesi quadre. La fattura resta in attesa di incasso.
• Se stava applicando un evento di GoCardless, il webhook risponde 500 affinché GoCardless rinvii la notifica, e gli eventi già applicati non vengono applicati due volte. Anche il recupero orario non lascia indietro un evento fallito: lo richiede di nuovo nel passaggio successivo.

Un 429 non equivale a un addebito senza risposta. Senza risposta, il connettore non sa se GoCardless ha creato l'addebito, quindi lo lascia in sospeso e lo rinvia, con la stessa chiave, entro un'ora. Con un 429 c'è una risposta: GoCardless non ha accettato la richiesta, e per questo la transazione finisce in errore.

Il connettore non è tradotto in italiano: questi testi compaiono sempre in inglese, anche in un Odoo in italiano, sia che li avvii un utente sia un'azione pianificata, come il rinnovo di un abbonamento: «GoCardless rejected the request.».

Cosa fare

• Apri la transazione dalla fattura, con il pulsante «Transazione di pagamento» in alto; il menu delle transazioni compare solo in modalità sviluppatore, e in Odoo 20 non esiste. Se il messaggio cita rate_limit_exceeded, GoCardless ha rifiutato quella richiesta per il limite, non per il cliente né per il suo mandato.
• Dopo un po', riprova a incassare la fattura con il metodo di pagamento salvato del cliente.
• Se succede spesso, controlla l'ora del server di Odoo: l'attesa si calcola sottraendola da quella di ratelimit-reset, e un orologio in anticipo la accorcia.
• Se ti serve GoCardless, conserva il request_id del messaggio: la loro documentazione chiede di includerlo quando si contatta il supporto.

Con il nostro connettore

In Odoo 17, 18, 19 e 20 il connettore tratta il 429 come una pausa: attende quanto indicato da GoCardless, ripete una volta e, se il limite persiste, lascia la transazione in errore con il request_id, così sai cosa è successo e cosa comunicare a GoCardless.

Continua a leggere