Gestisci i limiti di frequenza e gli errori del server

Gestisci una risposta 429

Una richiesta soggetta a limitazione restituisce 429 Too Many Requests con detail.status impostato su rate_limit_exceeded. Leggi le intestazioni della risposta prima di riprovare:

• Retry-After indica il tempo minimo, in secondi, da attendere per una richiesta rifiutata.
• X-RateLimit-Limit indica il limite del bucket.
• X-RateLimit-Remaining indica quante richieste restano.
• X-RateLimit-Reset indica quando il bucket viene ripristinato.

Attendi quanto indicato da Retry-After, quindi riprova con un backoff esponenziale e jitter. Riduci le richieste parallele e accodale invece di inviare un picco appena si riapre la finestra.

Gestisci gli errori del server

Per una risposta 500, il corpo pubblico contiene un errore generico e request_id; i dettagli delle eccezioni interne non vengono restituiti. Una risposta 503 può indicare che un servizio necessario è temporaneamente non disponibile.

Riprova le richieste di sola lettura applicando un backoff limitato. Prima di ripetere una richiesta di creazione, aggiornamento, pagamento o un'altra operazione che modifica lo stato, verifica se il primo tentativo è stato completato. Un timeout o una risposta 5xx non dimostrano che una modifica non sia riuscita: ripeterla subito può duplicare l'operazione.

Conserva le informazioni diagnostiche

Registra ora, metodo, percorso, stato, corpo della risposta e X-Request-Id. Non registrare mai il valore di x-api-key. Interrompi i tentativi automatici dopo un numero ridotto e limitato e segnala l'errore per la verifica.