Gestione avanzata degli errori

In questa pagina vengono trattati due argomenti avanzati relativi alla gestione degli errori:

• Risposte HTTP che rappresentano errori
• Idempotenza e nuovi tentativi

Queste informazioni potrebbero non essere applicabili al tuo caso. Gli SDK ufficiali di Stripe sono in grado di gestire la maggior parte dei dettagli che riguardano HTTP e tentativi ripetitivi. Se utilizzi una libreria client, inizia da qui:

• Gestione degli errori
• Codici di errore

Errori in HTTP

Anche quando una chiamata API non riesce, le nostre librerie client rendono disponibili le informazioni sull’errore generando un’eccezione o restituendo un valore di errore. Tuttavia, se non utilizzi una libreria client o se si verifica una situazione insolita, potrebbero essere necessari dettagli di basso livello sulle risposte HTTP e sul momento in cui vengono emesse.

Da un punto di vista del protocollo HTTP, gli errori si dividono in tre categorie principali:

• Errore di contenuto: contenuto non valido nella richiesta API.
• Errore di rete: problemi di comunicazione intermittenti tra client e server.
• Errore del server: un problema sui server di Stripe.

Ogni tipo di errore richiede un approccio e una semantica di idempotenza diversi. Alla fine di questa pagina è disponibile un elenco completo dei codici di risposta e il loro significato.

Errori di contenuto

Gli errori di contenuto sono il risultato di contenuti non validi di una richiesta API e restituiscono una risposta HTTP con un codice di risposta 4xx. Ad esempio, i server API potrebbero restituire un 401 se è stata specificata una chiave API non valida o un 400 se manca un parametro obbligatorio. Le integrazioni devono correggere la richiesta originale e riprovare. A seconda del tipo di errore dell’utente (ad esempio una carta rifiutata), il problema può essere gestito a livello di codice. In questi casi, includi un campo code per consentire a un’integrazione di reagire in modo appropriato. Per ulteriori informazioni, consulta la sezione dedicata ai codici di errore.

Nel caso di un’operazione POST che utilizza una chiave di idempotenza, i server API di Stripe salvano nella cache i risultati della richiesta indipendentemente da quali sono, a condizione che un metodo API abbia iniziato l’esecuzione. Una richiesta che restituisce un codice di errore 400 reinvierà lo stesso codice di errore se è eseguita nuovamente con la stessa chiave di idempotenza. Affinché il risultato sia corretto, devi generare una nuova chiave di idempotenza quando modifichi la richiesta originale. Tuttavia, questo metodo presenta alcune limitazioni. Ad esempio, una richiesta soggetta a un limite di frequenza e che restituisce un codice di errore 429 può produrre un risultato diverso con la stessa chiave di idempotenza perché i limitatori di frequenza vengono eseguiti prima del livello di idempotenza dell’API. Lo stesso vale per un codice 401 legato all’assenza di chiave API o per la maggior parte dei codici 400 legati a parametri non validi. Nonostante ciò, la strategia più sicura in caso di errori 4xx consiste nel generare sempre una nuova chiave di idempotenza.

Errori di rete

Gli errori di rete sono il risultato di problemi di connettività tra client e server e restituiscono errori di basso livello come le eccezioni socket o di timeout. Ad esempio, un client può andare in timeout durante un tentativo di lettura sui server di Stripe o non ricevere mai una risposta API perché la connessione è terminata prematuramente. Anche se un errore di rete sembra superato dopo aver risolto i problemi di connettività, a volte un altro tipo di errore si nasconde nel problema intermittente.

È in questa categoria di errori che il valore delle chiavi di idempotenza e dei nuovi tentativi di richiesta è più ovvio. Quando si verificano problemi intermittenti, i client solitamente rimangono in uno stato in cui non sanno se il server ha ricevuto la richiesta. Per ottenere una risposta definitiva, devono ritentare tali richieste con le stesse chiavi di idempotenza e gli stessi parametri finché non ricevono un risultato dal server. L’invio di una chiave di idempotenza identica con parametri diversi genera un errore indicante che la nuova richiesta non corrisponde all’originale.

La maggior parte delle librerie client possono generare chiavi di idempotenza e ritentare le richieste automaticamente, ma devono essere adeguatamente configurate. Effettuano il primo nuovo tentativo subito dopo il primo errore e i nuovi tentativi successivi in base a un backoff esponenziale. L’idea alla base di questo meccanismo è che un solo errore è spesso casuale, mentre errori ripetuti sono probabilmente il segno di un problema cronico.

Stripe.max_network_retries = 2

Errori del server

Gli errori del server sono il risultato di un problema con i server di Stripe e restituiscono una risposta HTTP con un codice di errore 5xx. Questi errori sono i più difficili da gestire e facciamo di tutto perché siano poco frequenti, ma una buona integrazione permette di affrontarli quando si verificano.

Come per gli errori utente, il livello di idempotenza salva nella cache il risultato delle mutazioni POST che generano errori del server (in particolare gli errori 500 che sono errori interni del server). Pertanto, effettuare nuovi tentativi con la stessa chiave di idempotenza in genere produce lo stesso risultato. Il client può ritentare la richiesta con una nuova chiave di idempotenza, ma questa strategia non è consigliata perché la chiave originale potrebbe aver prodotto effetti collaterali.

Il risultato di una richiesta 500 deve essere considerato indeterminato. È più probabile osservarlo durante un incidente di produzione, specialmente mentre si interviene per risolverlo. I tecnici di Stripe analizzano le richieste fallite e cercano di riconciliare accuratamente gli esiti delle modifiche che causano errori 500. Anche se la risposta memorizzata nella cache per queste richieste idempotenti non cambierà, attiveremo comunque i webhook per tutti i nuovi oggetti creati durante la riconciliazione di Stripe. L’esatta natura di eventuali modifiche retroattive nel sistema dipende fortemente dal tipo di richiesta. Ad esempio, se la creazione di un addebito restituisce un errore 500, ma rileviamo che le informazioni sono state inviate a un circuito di pagamento, proveremo a trasferirle in futuro. In caso contrario, proveremo a ripristinarlo. Se il problema non viene risolto, è possibile che vengano comunque visualizzate richieste con un errore 500 che producono effetti collaterali visibili all’utente.

Per consentire alla tua integrazione di gestire la più ampia gamma di errori 500, configura i gestori di webhook in modo da ricevere oggetti evento che abitualmente non ricevi nelle risposte API. Una tecnica per stabilire riferimenti incrociati tra questi nuovi oggetti e i dati dello stato locale di un’integrazione consiste nell’inviare un identificativo locale con i metadati al momento della creazione di nuove risorse con l’API. Tale identificativo viene visualizzato nel campo dei metadati di un oggetto inviato tramite un webhook, anche se il webhook viene generato in seguito come parte della riconciliazione.

Idempotenza

L’idempotenza è un principio di progettazione di un’API Web che consiste nel permettere di eseguire una stessa operazione più volte senza modificare il risultato oltre il primo tentativo. Consente di ritentare in tutta sicurezza le richieste API in alcune situazioni, in particolare quando la prima richiesta non riceve risposta a causa di un errore di rete. Poiché i malfunzionamenti occasionali sono inevitabili, i client devono poter riconciliare le richieste non riuscite con un server, operazione resa possibile dall’idempotenza.

La maggior parte delle librerie client può generare chiavi di idempotenza e ritentare le richieste automaticamente, ma devi configurarle. Per un controllo più granulare sui nuovi tentativi, genera chiavi di idempotenza e scrivi la tua logica per i nuovi tentativi.

Richieste GET e DELETE

L’API Stripe garantisce l’idempotenza delle richieste GET e DELETE, che possono quindi essere sempre ritentate in tutta sicurezza.

Richieste POST

Includendo una chiave di idempotenza, le richieste POST diventano idempotenti, vale a dire che viene richiesto all’API di tenere i registri necessari per evitare le operazioni duplicate. I client possono ritentare in modo sicuro le richieste che includono una chiave di idempotenza, a condizione che la seconda richiesta avvenga entro 24 ore dal primo ottenimento della chiave (le chiavi vengono cancellate dal sistema dopo 24 ore) Ad esempio, se una richiesta di creare un oggetto non risponde a causa di un errore di connessione di rete, un client può ritentarla con la stessa chiave di idempotenza per garantire che non venga creato più di un oggetto.

Inviare le chiavi di idempotenza

Le chiavi di idempotenza vengono inviate nell’intestazione Idempotency-Key. Utilizzale per tutte le richieste POST all’API Stripe. La maggior parte delle librerie client ufficiali può inviarle automaticamente, a condizione che siano configurate per l’invio di nuovi tentativi.

Se scegli di inviare manualmente le chiavi di idempotenza, assicurati che i token utilizzati siano sufficientemente distintivi da identificare in modo inequivocabile le singole operazioni eseguite nel tuo account almeno nelle ultime 24 ore. Due strategie sono comunemente utilizzate per generare chiavi di idempotenza:

• Utilizzare un algoritmo che genera un token con sufficiente casualità, come UUID v4.
• Ricavare la chiave da un oggetto associato all’utente, come l’ID di un carrello degli acquisti. Questo metodo permette di evitare i doppi invii in modo relativamente semplice.

Per identificare una risposta già eseguita e ritrasmessa dal server, cerca l’intestazione Idempotent-Replayed: true.

Intestazione Stripe-Should-Retry

Una libreria client non può determinare sempre con certezza se deve ritentare una richiesta unicamente sulla base di un codice di stato o del contenuto del corpo della richiesta L’API risponde con l’intestazione Stripe-Should-Retry quando dispone di informazioni supplementari indicanti che la richiesta può essere ritentata.

• Stripe-Should-Retry impostato su true indica che un client deve ritentare la richiesta. I client devono comunque attendere un po’ di tempo (probabilmente determinato in base a un backoff esponenziale) prima di effettuare la richiesta successiva in modo da non sovraccaricare l’API.
• Stripe-Should-Retry impostato su false indica che un client non deve ritentare la richiesta perché il nuovo tentativo non avrà ulteriori effetti.
• Stripe-Should-Retry non impostato nella risposta indica che l’API non è in grado di determinare se può o meno ritentare la richiesta. I client devono ricorrere ad altre proprietà della risposta (come il codice di stato) per prendere una decisione.

I meccanismi di rinnovo delle richieste integrati nelle librerie client di Stripe rispettano automaticamente l’intestazione Stripe-Should-Retry. Se stai usando uno di questi meccanismi, non devi effettuare una gestione manuale.

Riferimento dei codici di stato HTTP