Mensagens de erro comuns
Quando uma solicitação falha, a Bird retorna um erro estruturado com um código legível por máquina, uma mensagem, um link para a documentação e um ID de solicitação. Use o código na lógica do programa. Quando precisar de suporte, selecione Feedback > Contact us e inclua o ID de solicitação. Para o catálogo completo, consulte a referência de erros da API.
Erros de validação
Esses erros significam que a Bird entendeu sua solicitação, mas algo nela não é aceitável. O erro lista o campo ou a condição específica com problema.
Todos os destinatários suprimidos
O que significa: todos os destinatários do seu envio estão na sua lista de supressão, então não havia nada para entregar e o envio foi recusado.
Causa provável: você está enviando para endereços que anteriormente tiveram hard bounce, reclamaram ou cancelaram a inscrição, geralmente um sinal de que você está reenviando para uma lista antiga ou não higienizada. Se apenas alguns destinatários estão suprimidos, o envio prossegue para os demais e os suprimidos aparecem como rejeitados; esse erro só aparece quando são todos.
Correção: verifique quais endereços estão suprimidos e por quê, e remova-os da sua própria lista. Por que meu e-mail foi rejeitado? explica como as rejeições por supressão aparecem, e o guia de supressões cobre o gerenciamento da lista.
Destinatário de onboarding não permitido
O que significa: você está enviando a partir do domínio compartilhado de onboarding da Bird para alguém que não é um membro verificado do seu espaço de trabalho.
Causa provável: o domínio compartilhado entrega apenas para membros verificados do espaço de trabalho e endereços de teste do sandbox.
Correção: para enviar e-mails para destinatários reais, verifique seu próprio domínio de envio, o que remove a restrição completamente. Consulte Envio a partir do domínio compartilhado para as proteções e a saída.
Campo ausente ou inválido
O que significa: um campo obrigatório está ausente, um valor é inválido ou a solicitação combina campos incompatíveis.
Causa provável: a solicitação não corresponde ao schema da operação ou combina campos incompatíveis. Os detalhes do erro identificam cada campo com falha.
Correção: leia os detalhes do erro e corrija os campos indicados.
Erros de limitação de requisições
O que significa: a solicitação excedeu um limite de operação, conta ou envio.
Causa provável: um pico excedeu um limite de requisições da API, ou um envio excedeu uma cota como o limite de destinatários do domínio compartilhado de onboarding.
Correção: siga a remediação do erro e o valor Retry-After quando presente. Tente novamente limites transitórios com backoff. Para o limite diário de onboarding, aguarde a redefinição no dia UTC ou verifique seu próprio domínio de envio. O rótulo de saúde de e-mail throttled é diagnóstico e não causa um erro de limitação de requisições API.
Erros de autenticação
O que significa: a Bird não conseguiu aceitar suas credenciais.
Causa provável: uma de três situações, em ordem aproximada de frequência:
- Chave API errada, expirada ou revogada: a chave está digitada incorretamente, truncada, expirada ou não está mais ativa. O segredo é exibido apenas quando a chave é criada ou rotacionada.
- Chave usada na região errada: as chaves API são regionais, e uma chave só funciona nos servidores da sua própria região. Se sua chave foi criada em uma região e seu código chama outra, a autenticação falha. O prefixo da chave indica a qual região ela pertence.
- Chave ausente: a solicitação não incluiu credenciais, geralmente uma variável de ambiente que está vazia no ambiente onde a falha ocorre.
Correção: confirme que a chave existe e está ativa no seu dashboard, que seu código está enviando-a e que você está chamando o endereço regional correspondente à chave. Em caso de dúvida, crie uma nova chave e substitua.
Domínio não verificado
O que significa: o domínio de envio não concluiu a verificação, então a Bird não pode enviar a partir dele.
Causa provável: os registros DNS estão ausentes, ainda propagando ou incorretos, ou os registros mudaram após a verificação. Consulte o checklist de verificação de domínio para os prazos esperados.
Correção: abra a página do domínio no dashboard para identificar o registro pendente. Use o checklist de verificação de domínio para corrigi-lo. Enquanto o DNS propaga, use o domínio compartilhado de onboarding para envios de teste.
Lendo qualquer erro que você encontrar
Filtre pelo código de erro legível por máquina, porque as mensagens podem mudar. Registre o ID de solicitação. Se precisar de suporte, selecione Feedback > Contact us e inclua-o. Siga o link da documentação para a remediação específica do erro.
Próximos passos
- Referência de erros da API (o catálogo completo: cada tipo de erro, código e status)
- Por que meu e-mail foi rejeitado?: os motivos por trás das rejeições por destinatário
- Por que a saúde do e-mail mostra Throttled?: o rótulo diagnóstico de saúde e os sinais por trás dele
- Envio a partir do domínio compartilhado: as proteções de destinatários e limite diário do domínio de onboarding
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Assista ao guiaWhat happens when someone opts outEntenda o conceitoWhat is one-click unsubscribe, and how do I implement List-Unsubscribe?Explore a funcionalidadeEmail opt-outsSiga o percurso de aprendizagemOperate messaging reliably
Obtenha um resumo de implementação