Sign inGet Started

Respostas de erro

Toda requisição com falha retorna a mesma resposta de erro JSON sob uma chave de nível superior error, com um status HTTP que indica a categoria geral. Esta página é o contrato de comunicação; para orientações sobre ramificação, novas tentativas e a filosofia do catálogo de códigos, consulte Erros.
Exemplo de código
{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request validation failed.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01krdgeqcxet5s7t44vh8rt9mg",
    "details": [
      { "param": "contact_id", "message": "this field is reserved and not yet supported" },
      { "param": "topic_id", "message": "this field is reserved and not yet supported" }
    ]
  }
}

Campos da resposta de erro

CampoSempre presenteDescrição
typeSimCategoria geral para ramificação simples: um enum fechado (auth_error, validation_error, rate_limit_error, ...).
codeSimIdentificador opaco e estável correspondente a E\d{5}. Único, nunca renomeado, nunca reutilizado; o valor canônico para fazer matching.
nameSimSlug legível (ValidationError) para facilitar a leitura de logs. Sempre acompanhado de code, nunca um substituto para ele.
messageSimDescrição legível. Não é estável; exiba ou registre em log, nunca faça parsing.
doc_urlSimLink estável para a página de documentação deste code.
request_idSimID de correlação, também retornado como o header de resposta X-Request-Id. Cite-o em solicitações de suporte.
paramNãoO campo com problema, quando um único campo é o responsável pela falha.
detailsNãoFalhas de validação por campo como objetos {param, message}, onde param é um caminho separado por pontos como to[0].email. Presente apenas em respostas validation_error.
vendor_codeNãoCódigo literal de um sistema downstream (um código de resposta SMTP, um código de recusa de pagamento) quando vale a pena agir com base nele.

Mapeamento de status HTTP

Cada type mapeia para exatamente um status HTTP, de modo que o status e a resposta de erro nunca divergem.
StatustypeSignificado
400bad_request_errorA requisição estava malformada: um corpo impossível de parsear ou um header inválido (por exemplo, um Idempotency-Key incorreto).
401auth_errorA requisição continha credenciais ausentes, inválidas ou revogadas. Consulte Autenticação.
402billing_errorA requisição exige um método de pagamento, saldo ou plano que a organização não possui. Consulte Cobrança e uso.
403permission_errorAs credenciais são válidas, mas não têm permissão para executar esta requisição. Consulte Autenticação.
404not_found_errorNenhuma rota corresponde a este caminho, ou o recurso não existe neste espaço de trabalho. Consulte Regiões.
409conflict_errorA requisição conflita com o estado atual do recurso, incluindo conflitos de idempotência (E01004, E01005). Consulte Idempotência.
410gone_errorO recurso existia, mas foi removido permanentemente.
412precondition_errorUma pré-condição para esta requisição não foi atendida.
413payload_too_large_errorO corpo da requisição excede o tamanho máximo permitido.
421misdirected_errorA requisição chegou a uma região que não pode atendê-la. Consulte Regiões.
422delivery_errorA mensagem foi aceita como requisição, mas não pode ser entregue no endereço informado.
422validation_errorO corpo da requisição foi parseado, mas um ou mais valores são inválidos.
425too_early_errorA requisição chegou antes de poder ser processada.
429rate_limit_errorUm grupo de limitação de requisições está esgotado para este espaço de trabalho. Consulte Limites de requisições.
499client_closed_request_errorA conexão foi encerrada antes de a resposta ficar pronta, geralmente porque o chamador parou de aguardar.
500internal_errorAlgo falhou do nosso lado ao processar a solicitação. Consulte Idempotência.
501not_implemented_errorO endpoint está declarado na API, mas ainda não foi implementado.
503service_unavailable_errorAlgo de que esta solicitação depende está temporariamente indisponível.

Tratamento de erros nos SDKs

Cada SDK mapeia a resposta de erro para o modelo de erro nativo da linguagem e carrega todos os campos da resposta de erro (type, code, message, doc_url, request_id, ...) no valor do erro.
import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";

try {
  await bird.email.send({
    from: { email: "onboarding@messagebird.dev", name: "Bird" },
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Bird",
    html: "<p>My first Bird email.</p>",
  });
} catch (err) {
  if (err instanceof BirdRateLimitError) console.log(`rate limited; retry in ${err.retryAfter}s`);
  else if (err instanceof BirdValidationError) console.error(err.details);
  else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
  else throw err;
}

Catálogo de erros

Todos os códigos de erro que a Bird API pública retorna, divididos em uma página por faixa de códigos. Cada página de faixa lista seus códigos, e cada código tem sua própria página com a causa e o que fazer. O doc_url em qualquer resposta de erro leva diretamente à página daquele código.
FaixaÁreaCódigos
E01xxxInfraestrutura30 códigos, 2 descontinuados
E02xxxAutenticação e identidade9 códigos, 2 descontinuados
E03xxxCobrança e planos12 códigos
E04xxxEnvio e entrega de e-mail67 códigos, 3 aposentados
E05xxxDomínios e DNS19 códigos
E06xxxWebhooks7 códigos
E07xxxWallet4 códigos
E10xxxCotas9 códigos, 2 descontinuados
E11xxxPools de IP e IPs dedicados4 códigos, 1 aposentado
E12xxxEnvio e entrega SMS49 códigos, 5 descontinuados
E13xxxVerify7 códigos, 1 aposentado
E14xxxNúmeros5 códigos
E15xxxEnvio e entrega WhatsApp49 códigos
E16xxxTrust1 código
E17xxxCaixas de correio de agentes14 códigos, 2 aposentados
E19xxxConformidade de registro4 códigos
E21xxxVoz e trunking SIP16 códigos, 7 aposentados
E22xxxConsulta de número4 códigos
E23xxxRealtime1 código
E24xxxCompetitive Insights6 códigos
E25xxxSendability5 códigos, 1 descontinuado
E27xxxInbox Insights5 códigos
E28xxxApple Messages for Business29 códigos, 2 aposentados
E32xxxConfirmação de operação6 códigos

Relacionados