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, cada um como `{param, message}`. Presente apenas em respostas `validation_error`, e somente naquelas que listam campos.
`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. Para transformar um em texto claro, leia o message do erro e abra o doc_url: cada código tem uma página que diz o que deu errado e o que fazer. 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. A maioria dos problemas de campo é E01001 ValidationError. O message de nível superior diz o que está errado e param nomeia o campo. Um array details lista cada problema por campo como {param, message}, da mesma forma que a falha de envio capturada lista suas propriedades ausentes. Uma propriedade de contato é nomeada pela sua chave em data, como data.plan. Alguns erros de validação nomeiam um único campo em param e não trazem details, então leia details quando estiver presente. As strings message 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

Continue com a documentação, guias e exemplos sobre este tópico.

Obtenha um resumo de implementação