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 retornado.

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 Limitação 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 requisição. Consulte Idempotência.
501not_implemented_errorO endpoint está declarado na API, mas ainda não foi implementado.
503service_unavailable_errorAlgo de que esta requisiçã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 identidade24 códigos, 2 descontinuados
E03xxxCobrança e planos15 códigos, 2 descontinuados
E04xxxEnvio e entrega de e-mail87 códigos, 3 descontinuados
E05xxxDomínios e DNS19 códigos
E06xxxWebhooks11 códigos
E07xxxWallet4 códigos
E08xxxGestão de espaços de trabalho e organizações1 código, 2 descontinuados
E10xxxCotas16 códigos, 2 descontinuados
E11xxxPools de IP e IPs dedicados4 códigos, 1 descontinuado
E12xxxEnvio e entrega de SMS62 códigos, 5 descontinuados
E13xxxVerify7 códigos, 1 descontinuado
E14xxxNúmeros6 códigos
E15xxxEnvio e entrega de WhatsApp75 códigos
E16xxxTrust1 código
E17xxxCaixas de correio de agentes16 códigos, 2 descontinuados
E19xxxConformidade de registro6 códigos
E20xxxAtivos e biblioteca de mídia15 códigos
E21xxxVoz e trunking SIP20 códigos, 9 descontinuados
E22xxxConsulta de número5 códigos
E23xxxRealtime1 código
E24xxxCompetitive Insights6 códigos
E25xxxSendability5 códigos, 1 descontinuado
E26xxxeSIM19 códigos
E27xxxInbox Insights9 códigos
E28xxxApple Messages for Business48 códigos, 2 descontinuados
E32xxxConfirmação de operação6 códigos
E33xxxElegibilidade da organização3 códigos, 1 descontinuado
E34xxxConectores1 código, 1 descontinuado

Relacionados