Limiti di frequenza API Astrina: diagnosi e risposta

Header e campi dei limiti di frequenza da controllare per primi

Parti dalla risposta stessa. Se una richiesta viene rifiutata, di solito gli header e i metadati dicono più del testo dell’errore, ed è qui che i limiti di frequenza API Astrina diventano più facili da interpretare.

Cerca i campi che indicano l’orario di reset, il credito residuo e la categoria del limite. Se Astrina restituisce dati di classificazione, tienili nel log perché lo stesso endpoint può comportarsi in modo diverso a seconda del tipo di richiesta. Quando stai risolvendo problemi di limiti di frequenza dell’API Astrina, questo è particolarmente importante perché piccole differenze negli header possono spiegare perché una chiamata va a buon fine e la successiva fallisce.

Una piccola abitudine fa risparmiare tempo dopo: registra l’orario esatto della richiesta, non solo l’errore. Un valore di reset che sembra “strano” spesso è solo un disallineamento dell’orologio. L’ho visto più di una volta.

Se il tuo client memorizza già i codici di stato, aggiungi i relativi header rate limit Astrina accanto a quelli. Così è più facile individuare uno schema quando il limite viene raggiunto alle 09:00 e di nuovo alle 09:03. Due numeri raccontano la storia più in fretta di un paragrafo di ipotesi.

Su astrina, è questo il tipo di dettaglio che aiuta un’integrazione a passare dalle supposizioni alle prove. L’obiettivo è semplice: sapere se sei bloccato, per quanto dura il blocco e quale tipo di richiesta l’ha causato.

Distinguere i limiti per utente, per chiave e per endpoint

Non tutti i limiti sono uguali. Un singolo utente può superare un limite basato sull’utente mentre la stessa chiave continua a funzionare per un altro account, e un tetto specifico per endpoint può bloccare un percorso mentre il resto dell’API resta disponibile.

Questa distinzione conta perché cambia la soluzione. Se una credenziale è esaurita, può avere senso instradare le richieste tramite un’altra chiave. Se un endpoint è limitato, spostare il traffico su percorsi non correlati non aiuta. Se l’intero account è soggetto a vincoli, il problema è più ampio di un singolo token.

Controlla quale richiesta fallisce per prima. Poi ripeti la stessa chiamata con un utente diverso, una chiave diversa o un percorso diverso, cambiando una sola variabile alla volta. Tre test, non dieci, spesso bastano per individuare il confine.

Pensalo come una mappa con tre serrature. La serratura di una porta non significa che l’intero edificio sia chiuso. Potrebbe essere solo la porta che hai scelto.

Un indizio pratico è la ripetizione. Se le richieste a `/search` falliscono mentre `/status` continua a funzionare, è più probabile un limite per endpoint. Se entrambe falliscono solo per una credenziale, il limite è probabilmente legato a quell’identità.

Cosa significa in pratica una risposta “rate limited”

Una risposta “rate limited” significa che il server ha deciso che la richiesta corrente non è consentita in questo momento. Non significa automaticamente che l’account sia rotto, la chiave non sia valida o il sistema sia guasto.

Altre richieste potrebbero comunque andare a buon fine altrove. Un endpoint ad alto volume di lettura può essere bloccato mentre un endpoint meno trafficato risponde normalmente. Per questo il client non dovrebbe presumere che l’intera sessione sia morta dopo un solo rifiuto.

Registra il contesto completo di ogni errore: endpoint, ID della credenziale, orario della richiesta, codice di stato e qualsiasi request ID restituito dall’API. Senza questi cinque elementi, il supporto deve ricostruire la scena a partire da frammenti.

Un errore comune lato client è trattare ogni rifiuto come lo stesso evento. Non lo è. Un limite di frequenza è temporaneo, mentre un errore di autenticazione di solito non lo è. Confondere le due cose porta a retry sbagliati e a interruzioni più lunghe.

Su ogni sito che gestisci, vale la stessa regola: una richiesta bloccata va etichettata come bloccata, non semplicemente “fallita”. Questa piccola etichetta mantiene onesti i dashboard.

Comportamento immediato del client dopo il throttling

Dopo un throttling, smetti di inviare la stessa richiesta in un loop serrato. Un frontend dovrebbe mettere in pausa quell’azione, un job backend dovrebbe spostare l’elemento in una coda di retry e un’integrazione dovrebbe attendere la prossima chiamata fino a quando non sia passato il tempo di reset o la finestra di backoff, cioè la base di come gestire rate limit API.

Per i flussi interattivi, mostra un messaggio breve e un percorso di riprova. Per i job, preferisci una coda con un campo di ritardo chiaro. Per gli script, esci in modo pulito e lascia che sia lo scheduler a riprovare più tardi. Tre ambienti, tre reazioni.

Non continuare a martellare lo stesso endpoint. Se 20 richieste sono già state bloccate, la 21ª non è più convincente.

Conserva il payload originale. Se la richiesta può essere ripetuta in sicurezza, memorizza dati sufficienti per ricostruirla esattamente quando l’attesa finisce. Se la richiesta crea stato, assicurati che il server possa gestire i duplicati, perché un retry ritardato può arrivare dopo che il primo tentativo è finalmente andato a buon fine.

Questo è anche il punto in cui separare la latenza percepita dall’utente dal comportamento del sistema. Uno spinner può aspettare 5 secondi; un job runner può aspettare 5 minuti. Il client dovrebbe sapere qual è il caso.

Backoff e tempi di retry per brevi raffiche

Le raffiche brevi richiedono disciplina. Parti con un ritardo, poi allunga l’attesa dopo ogni retry fallito usando l’exponential backoff, e aggiungi jitter se il tuo client lo supporta.

Il jitter conta perché i retry sincronizzati fanno rumore. Se 50 worker si risvegliano tutti nello stesso secondo, possono creare una seconda ondata di pressione. È così che un throttling breve diventa lungo.

Usa un numero massimo di tentativi. Cinque tentativi possono bastare per una breve raffica; cinquanta sono di solito il segnale che il client sta ignorando il limite invece di rispettarlo.

Funziona bene un pattern semplice: attendi 1 secondo, poi 2, poi 4, poi 8, aggiungendo un piccolo offset casuale. I numeri esatti possono cambiare da sistema a sistema, ma la forma del comportamento dovrebbe restare calma e prevedibile.

Se l’API pubblica un tempo di reset, preferiscilo alle supposizioni. Se non lo fa, il backoff è una strada più sicura del polling aggressivo. Una richiesta in più può essere costosa quando il limite è già in vista.

Separare il throttling temporaneo dagli errori di autenticazione o autorizzazione

I limiti di frequenza e gli errori di accesso sono parenti, non gemelli. Un token sbagliato fallisce quasi sempre. Un throttling fallisce solo sotto pressione.

Prova la stessa credenziale su un endpoint a basso costo. Se quella richiesta funziona, il token è probabilmente valido e il problema è verosimilmente il volume, non l’autenticazione. Se fallisce con lo stesso schema, il problema potrebbe essere autorizzazione, scadenza o una chiave revocata.

Osserva insieme il codice di stato e il corpo della risposta. Una risposta di limite spesso ha una forma diversa da una risposta per credenziali non valide, anche se entrambe arrivano come errori della classe 4xx. Il body può indicare il tipo di limite, mentre un problema di permessi può parlare di scope o accesso negato.

Non rigenerare la credenziale alla prima risposta negativa. Potresti sprecare ore. Verifica se il problema è legato al carico, all’identità o a un grant mancante.

Un passo diagnostico pulito è confrontare una chiamata riuscita fatta prima nella giornata con quella che fallisce. Stessa chiave, stesso endpoint, risultato diverso. Quel contrasto di solito restringe rapidamente il problema.

Monitorare gli eventi di rate limit nei log e negli alert

I log dovrebbero rispondere a quattro domande: quanto spesso, dove, chi e per quanto tempo. La frequenza mostra la scala. L’endpoint interessato mostra il punto caldo. Il request ID collega il supporto alla chiamata esatta. Il tempo di recupero mostra se il client ha atteso abbastanza.

Genera alert su throttling ripetuti, non su un singolo picco. Una raffica fallita può essere un utente che clicca due volte. Dieci eventi in due minuti sono uno schema che merita attenzione.

Conserva il request ID nel payload dell’alert. Aggiungi l’utente, la chiave o il nome del job, se il tuo sistema li ha. Così l’alert è utile sia al team di engineering sia al supporto.

Una riga di log pulita potrebbe includere endpoint, stato, categoria del limite, tempo di reset e numero di retry. Cinque campi bastano per la maggior parte delle indagini. Di più va bene, ma meno tende a trasformarsi in una caccia al tesoro.

Se stai confrontando il traffico tra prodotti, astrina può aiutare a mantenere visibile la stessa attività in un unico posto. Conta quando un dashboard mostra una lieve crescita e un altro mostra un picco brusco.

Quando escalare al supporto Astrina

Escala quando il traffico normale continua a essere limitato anche dopo aver verificato il comportamento del client, la combinazione degli endpoint e i tempi di retry. Un limite che scatta nell’uso ordinario non è qualcosa su cui convenga tirare a indovinare a lungo.

Porta prove. Includi timestamp, request ID, nome dell’endpoint, riferimento alla credenziale o all’account e il comportamento di reset osservato. Un ticket di supporto con questi cinque elementi è molto più facile da gestire di un semplice “continua a fallire”.

Escala anche se il comportamento del limite appare incoerente. Se la stessa richiesta è consentita alle 10:01 e bloccata alle 10:02 senza un cambiamento significativo del volume, merita un’analisi più approfondita.

C’è un altro caso che spicca: se la tua integrazione è piccola ma condivisa tra molti team, una raffica apparentemente modesta può sembrare un evento di sistema più grande. In quel caso, il supporto può confermare se si sta raggiungendo il limite a livello di account o se un job si sta comportando male.

Se il tuo caso d’uso coinvolge più proprietà, ogni sito cliente in un unico dashboard può rendere l’indagine più pulita, perché lo stesso evento di limite può essere tracciato tra account diversi senza saltare da uno strumento all’altro.

Mantieni la conversazione specifica. “Abbiamo raggiunto il limite tre volte tra le 14:10 e le 14:18 su `/reports` con la chiave X” è un elemento su cui si può intervenire. “L’API è lenta” no. La prima frase punta a un limite. La seconda punta a una sensazione.