Um remetente com alto volume pode esgotar seu orçamento de requisições antes de todas as mensagens entrarem na fila. Ler a cota restante permite reduzir o ritmo antes que mais chamadas sejam recusadas.
Como o Bird decide meu limite?
O Bird aplica uma taxa base, qualquer aumento do plano e então qualquer override para o grupo relevante. Um override substitui os outros valores.
Endpoints relacionados compartilham um grupo. Esgotar um grupo de envio não esgota por si só os grupos separados usados para ler status ou gerenciar webhooks.
O escopo de cada orçamento depende da operação:
| Grupo | Quem compartilha o orçamento? |
|---|---|
| Envios de produto | Todas as credenciais da organização para aquele produto. |
| Leituras, listagens e escritas de gerenciamento | Requisições da mesma credencial atuante dentro da organização. |
| Login ou redefinição de senha não autenticados | Requisições do mesmo IP de cliente. |
Limites não autenticados usam limiares fixos. Consulte o guia de limites de requisições para os grupos atribuídos a cada endpoint.
Limites de envio contam requisições, não destinatários. Uma requisição em lote pode enfileirar várias mensagens. Seu grupo pode ter uma cota diferente.
Compare as cotas em tempo real e o número de destinatários que você pode agrupar antes de trocar de endpoint. Um lote com apenas um destinatário pode não trazer ganho de throughput.
Como leio os headers de resposta?
Leia RateLimit-Policy para a cota e a janela, depois RateLimit para as requisições restantes e o tempo até o reset.
Por exemplo:
RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35Este exemplo permite 1.000 requisições por janela de 60 segundos. Restam 842 requisições, com 35 segundos até o reset.
Os números ilustram os headers. Eles não são uma cota garantida. Leia os valores retornados ao seu cliente.
| Campo | Significado |
|---|---|
| Nome entre aspas | O grupo ao qual a política se aplica. |
q | Requisições permitidas por janela. |
w | Duração da janela em segundos. |
r | Requisições restantes. |
t | Segundos até o reset, não um timestamp. |
Uma resposta pode conter mais de uma política. Considere todas as políticas aplicáveis ao agendar a próxima requisição.
O que uma falha de limitação de requisições retorna?
Um limite API esgotado retorna 429 Too Many Requests com Retry-After em segundos. Os headers de limitação de requisições identificam o grupo esgotado. Sua cota restante é r=0.
A resposta de erro inclui estes campos:
{
"error": {
"type": "rate_limit_error",
"code": "E01003",
"name": "RateLimited"
}
}Use o type ou code no seu handler. A mensagem legível pode mudar sem alterar a ação de recuperação.
Como meu cliente deve lidar com um 429?
Aguarde Retry-After, depois tente novamente com uma política de backoff limitada. Mantenha a mesma chave de idempotência ao repetir a mesma escrita.
Coordene workers que usam o mesmo orçamento de grupo. A última resposta de um worker não reflete requisições que outros workers enviaram desde então.
Reduza o ritmo à medida que a cota restante diminui. Mantenha o caminho de retry para tráfego concorrente. O controle de ritmo reduz falhas, mas não garante que nenhuma chamada receba um 429.
Os SDKs do Bird lidam com retries de 429 e Retry-After. Eles não coordenam uma fila compartilhada entre todos os seus processos.
Se a cota permanecer baixa demais para a carga de trabalho, entre em contato com o Bird sobre um override. Criar mais chaves não aumenta o limite de envio da organização.
Uma requisição limitada executou algum trabalho?
O Bird rejeita uma requisição limitada antes de executar o trabalho solicitado. Essa rejeição não consome a chave de idempotência. Tente novamente com a mesma chave após aguardar.
O limitador permite a passagem de requisições se não conseguir avaliar o limite. Um problema ao avaliar cotas, portanto, não produz por si só um 429.
Mantenha o tratamento de idempotência para outras falhas também. Um erro de servidor ou resposta perdida pode ocorrer após o início de uma escrita.
Em resumo
Leia a cota nas respostas.
O limite aplicável depende do grupo, do plano e de qualquer override. Um número fixo pode ficar desatualizado.
Coordene remetentes que compartilham uma cota.
Limites de envio se aplicam a toda a organização, então chaves separadas não criam orçamentos de envio separados.
Aguarde antes de tentar novamente após um 429.
Retry-Afterinforma o atraso em segundos. Limite suas tentativas. Preserve a chave de idempotência para a mesma escrita.Trate os headers como estado compartilhado.
Requisições restantes podem ser consumidas por outros workers, então o controle de ritmo reduz falhas de limitação de requisições sem eliminá-las.