Erros

Toda solicitação Bird API que falha retorna a mesma resposta de erro JSON, aninhada sob uma chave de nível superior error. Esta é uma resposta real a uma solicitação de envio com corpo vazio:

Exemplo de código

{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request has 1 validation error.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01ky7q3hckecgv6d7jpq865532",
    "details": [{ "param": "body", "message": "missing properties 'from', 'to'" }]
  }
}

O status HTTP decorre do type. Erros do cliente usam 400 para solicitações malformadas, 401 ou 403 para falhas de acesso, 402 para cobrança e 404 para recursos não encontrados. Usam 409 para conflitos, 412 para pré-condições não atendidas, 422 para falhas de validação e regras de negócio e 429 para limitação de requisições. Falhas do lado do Bird usam 5xx. O status identifica a categoria; a resposta de erro explica o que aconteceu.

Campos da resposta de erro

Campo	Função
type	Categoria ampla para ramificação geral: validation_error, auth_error, permission_error, not_found_error, conflict_error, rate_limit_error, billing_error, internal_error e alguns outros. Um enum fechado que cresce raramente.
code	Identificador opaco e estável (E01001). A referência canônica: único, nunca renomeado, nunca reutilizado. Quando um erro é aposentado, seu código fica permanentemente reservado.
name	Slug legível por humanos (ValidationError) para facilitar a leitura de logs. Sempre acompanha code, nunca o substitui.
message	Descrição legível por humanos. Não é estável: o texto pode mudar sem aviso. Exiba, registre em log, nunca faça parsing.
param	Para erros relacionados à entrada, o campo com problema. Omitido quando não aplicável.
doc_url	Link estável para a página de documentação deste código.
request_id	Sempre presente, e também retornado como header de resposta X-Request-Id. Inclua-o em solicitações de suporte; ele permite que Bird rastreie a solicitação exata.
details	Problemas de validação por campo. Presente apenas em respostas validation_error.
remediation	Próximo passo legível por humanos para resolver o erro. Presente quando uma recuperação é conhecida.
next	Operações que resolvem o erro, na ordem em que devem ser tentadas. Presente para erros com recuperação bem definida, como pré-condições não atendidas.
vendor_code	Código literal de um sistema downstream (um código de resposta SMTP, um código de recusa de pagamento). Presente apenas quando Bird está expondo o código de um sistema externo no qual você pode querer agir.

Ramifique em type para tratamento geral e em code para tratamento específico, nunca em message. Um cliente típico faz switch em type (tentar novamente em rate_limit_error, exibir validation_error para o usuário, acionar alguém em internal_error) e faz match de valores individuais de code apenas para os poucos erros que trata de forma especial.

Códigos como E04012 são intencionalmente opacos. Cada código aponta para uma página de documentação por meio de doc_url, que explica a causa e como resolver. O catálogo completo está na referência de erros.

Falhas de validação: um código, muitos detalhes

A validação por campo não recebe um código separado para cada combinação de campo e falha. Toda falha de validação é E01001 ValidationError com um array details listando cada problema por campo como {param, message}, da mesma forma que a falha de envio capturada lista suas propriedades ausentes. As strings message dentro de details podem mudar e devem apenas ser exibidas. Use param para mapear problemas aos campos do formulário.

Orientação de recuperação: correção e próximo passo

Erros com uma correção conhecida a incluem na resposta de erro. Esta é uma resposta real a uma chamada de webhooks feita com uma chave API que não possui o escopo necessário:

Exemplo de código

{
  "error": {
    "type": "permission_error",
    "code": "E02035",
    "name": "InsufficientScope",
    "message": "This request requires the \"webhooks:read\" scope, which your credential has not been granted.",
    "param": "webhooks:read",
    "doc_url": "https://bird.com/docs/api/errors/E02035",
    "request_id": "req_01ky7q4665emc9tw1pxkptaqwq",
    "remediation": "Re-authenticate with a credential that has been granted the required scope, then retry."
  }
}

remediation é uma frase para um humano ou log de agente; next, quando presente, lista as operações API que resolvem o erro na ordem em que devem ser tentadas (verificar um domínio, depois tentar novamente o envio). Agentes e CLIs podem executar next diretamente; clientes interativos podem exibir remediation como está.

Tratando erros bem

Tente novamente em 429 e 5xx, nada mais por padrão. Respeite Retry-After na limitação de requisições (veja Limitação de requisições), use backoff exponencial em 5xx e envie um Idempotency-Key para que retentativas de solicitações mutáveis sejam seguras.
Registre code, name e request_id juntos. O código é o que você vai buscar na documentação e nos seus próprios logs; o ID da solicitação é o que o suporte precisa.
Tolere novos códigos e tipos. Novos códigos de erro são lançados regularmente conforme os produtos crescem, e o enum type ocasionalmente ganha um valor. Escreva seu handler com um branch padrão razoável em vez de um match exaustivo.

Próximos passos

Referência de erros: o catálogo completo de erros, uma página por código
Idempotência: retentativas seguras para solicitações mutáveis
Limitação de requisições: headers de limite e orientação de backoff

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Entenda o conceitoShould I use a Bird SDK or call the API directly?Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first email

Obtenha um resumo de implementação