Un mittente intensivo può esaurire il proprio budget di richieste prima che tutti i messaggi siano in coda. Leggere la quota rimanente permette di rallentare prima che altre chiamate vengano rifiutate.
Come decide Bird il mio limite?
Bird applica un tasso base, un eventuale incremento del piano e poi un eventuale override per il gruppo pertinente. Un override sostituisce gli altri valori.
Endpoint correlati condividono un gruppo. Esaurire un gruppo di invio non esaurisce di per sé i gruppi separati usati per leggere lo stato o gestire i webhook.
L'ambito di ogni budget dipende dall'operazione:
| Gruppo | Chi condivide il budget? |
|---|---|
| Invii di prodotto | Tutte le credenziali nell'organizzazione per quel prodotto. |
| Letture, elenchi e scritture gestionali | Richieste dalla stessa credenziale operante nell'organizzazione. |
| Login o reset password non autenticati | Richieste dallo stesso IP client. |
I limiti non autenticati usano soglie fisse. Consulta la guida ai limiti delle richieste per i gruppi assegnati ai singoli endpoint.
I limiti di invio contano le richieste, non i destinatari. Una richiesta batch può accodare più messaggi. Il suo gruppo può avere una quota diversa.
Confronta le quote attive e il numero di destinatari raggruppabili prima di cambiare endpoint. Un batch con un solo destinatario potrebbe non offrire alcun vantaggio di throughput.
Come leggo gli header di risposta?
Leggi RateLimit-Policy per la quota e la finestra, poi RateLimit per le richieste rimanenti e il tempo al reset.
Per esempio:
RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35Questo esempio consente 1.000 richieste per finestra di 60 secondi. Ha 842 richieste rimanenti, con 35 secondi al reset.
I numeri illustrano gli header. Non rappresentano una quota garantita. Leggi i valori restituiti al tuo client.
| Campo | Significato |
|---|---|
| Nome citato | Il gruppo a cui si applica la policy. |
q | Richieste consentite per finestra. |
w | Durata della finestra in secondi. |
r | Richieste rimanenti. |
t | Secondi al reset, non un timestamp. |
Una risposta può contenere più di una policy. Tieni conto di ogni policy applicabile quando pianifichi la richiesta successiva.
Cosa restituisce un errore di limitazione delle richieste?
Un limite API esaurito restituisce 429 Too Many Requests con Retry-After in secondi. Gli header di limitazione identificano il gruppo esaurito. La sua quota rimanente è r=0.
La risposta di errore include questi campi:
{
"error": {
"type": "rate_limit_error",
"code": "E01003",
"name": "RateLimited"
}
}Confronta il type o il code nel tuo handler. Il messaggio leggibile può cambiare senza modificare l'azione di recupero.
Come dovrebbe gestire un 429 il mio client?
Attendi Retry-After, poi riprova con una policy di backoff limitata. Mantieni la stessa chiave di idempotenza quando ripeti la stessa scrittura.
Coordina i worker che usano lo stesso budget di gruppo. L'ultima risposta di un worker non può tenere conto delle richieste inviate nel frattempo da altri worker.
Rallenta man mano che la quota rimanente diminuisce. Conserva il percorso di retry per il traffico concorrente. Il dosaggio riduce gli errori ma non può garantire che nessuna chiamata riceva un 429.
Gli SDK Bird gestiscono i retry dei 429 e Retry-After. Non coordinano una coda condivisa tra tutti i tuoi processi.
Se la quota resta troppo bassa per il carico di lavoro, contatta Bird per un override. Creare più chiavi non aumenta il limite di invio a livello di organizzazione.
Una richiesta limitata ha eseguito qualche operazione?
Bird rifiuta una richiesta limitata prima di eseguire il lavoro richiesto. Quel rifiuto non consuma la chiave di idempotenza. Riprova con la stessa chiave dopo aver atteso.
Il limitatore lascia passare le richieste se non riesce a valutare il limite. Un problema nella valutazione delle quote quindi non produce di per sé un 429.
Mantieni la gestione dell'idempotenza anche per altri errori. Un errore del server o una risposta persa possono verificarsi dopo che una scrittura è iniziata.
In breve
Leggi la quota dalle risposte.
Il limite applicabile dipende dal gruppo, dal piano e da eventuali override. Un numero fisso può diventare errato.
Coordina i mittenti che condividono una quota.
I limiti di invio si applicano a livello di organizzazione, quindi chiavi separate non creano budget di invio separati.
Attendi prima di riprovare un 429.
Retry-Afterindica il ritardo in secondi. Limita i tuoi tentativi. Mantieni la chiave di idempotenza per la stessa scrittura.Tratta gli header come stato condiviso.
Le richieste rimanenti possono essere consumate da altri worker, quindi il dosaggio riduce gli errori di limitazione senza eliminarli.