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
| Campo | Sempre presente | Descrição |
|---|---|---|
| type | Sim | Categoria geral para ramificação simples: um enum fechado (auth_error, validation_error, rate_limit_error, ...). |
| code | Sim | Identificador opaco e estável correspondente a E\d{5}. Único, nunca renomeado, nunca reutilizado; o valor canônico para fazer matching. |
| name | Sim | Slug legível (ValidationError) para facilitar a leitura de logs. Sempre acompanhado de code, nunca um substituto para ele. |
| message | Sim | Descrição legível. Não é estável; exiba ou registre em log, nunca faça parsing. |
| doc_url | Sim | Link estável para a página de documentação deste code. |
| request_id | Sim | ID de correlação, também retornado como o header de resposta X-Request-Id. Cite-o em solicitações de suporte. |
| param | Não | O campo com problema, quando um único campo é o responsável pela falha. |
| details | Não | Falhas 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_code | Não | Có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.
| Status | type | Significado |
|---|---|---|
| 400 | bad_request_error | A requisição estava malformada: um corpo impossível de parsear ou um header inválido (por exemplo, um Idempotency-Key incorreto). |
| 401 | auth_error | A requisição continha credenciais ausentes, inválidas ou revogadas. Consulte Autenticação. |
| 402 | billing_error | A requisição exige um método de pagamento, saldo ou plano que a organização não possui. Consulte Cobrança e uso. |
| 403 | permission_error | As credenciais são válidas, mas não têm permissão para executar esta requisição. Consulte Autenticação. |
| 404 | not_found_error | Nenhuma rota corresponde a este caminho, ou o recurso não existe neste espaço de trabalho. Consulte Regiões. |
| 409 | conflict_error | A requisição conflita com o estado atual do recurso, incluindo conflitos de idempotência (E01004, E01005). Consulte Idempotência. |
| 410 | gone_error | O recurso existia, mas foi removido permanentemente. |
| 412 | precondition_error | Uma pré-condição para esta requisição não foi atendida. |
| 413 | payload_too_large_error | O corpo da requisição excede o tamanho máximo permitido. |
| 421 | misdirected_error | A requisição chegou a uma região que não pode atendê-la. Consulte Regiões. |
| 422 | delivery_error | A mensagem foi aceita como requisição, mas não pode ser entregue no endereço informado. |
| 422 | validation_error | O corpo da requisição foi parseado, mas um ou mais valores são inválidos. |
| 425 | too_early_error | A requisição chegou antes de poder ser processada. |
| 429 | rate_limit_error | Um grupo de limitação de requisições está esgotado para este espaço de trabalho. Consulte Limites de requisições. |
| 499 | client_closed_request_error | A conexão foi encerrada antes de a resposta ficar pronta, geralmente porque o chamador parou de aguardar. |
| 500 | internal_error | Algo falhou do nosso lado ao processar a solicitação. Consulte Idempotência. |
| 501 | not_implemented_error | O endpoint está declarado na API, mas ainda não foi implementado. |
| 503 | service_unavailable_error | Algo 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;
}from bird import APIStatusError, RateLimitError, ValidationError
try:
client.email.send(
from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
to=["delivered@messagebird.dev"],
subject="Hello from Bird",
text="My first Bird email.",
)
except RateLimitError as err:
print("rate limited; retry after", err.retry_after)
except ValidationError as err:
print(err.status_code, err.details)
except APIStatusError as err:
print(err.status_code, err.code, err.request_id)if err != nil {
var rle *bird.RateLimitError
var ve *bird.ValidationError
var ae *bird.APIError
switch {
case errors.As(err, &rle):
fmt.Println("rate limited; retry after", rle.RetryAfter)
case errors.As(err, &ve):
for _, d := range ve.Details {
fmt.Printf("%s: %s\n", d.Param, d.Message)
}
case errors.As(err, &ae):
fmt.Printf("API error %s (status %d, request %s)\n", ae.Code, ae.StatusCode, ae.RequestID)
default:
log.Print(err) // transport: *bird.ConnectionError or *bird.TimeoutError
}
}try {
$bird->email->send(
from: 'Bird <onboarding@messagebird.dev>',
to: ['delivered@messagebird.dev'],
subject: 'Hello from Bird',
html: '<p>My first Bird email.</p>',
);
} catch (ApiException $e) {
// The server returned an error response. $status is the HTTP status, $type
// the coarse category, $errorCode the stable E##### code.
echo $e->status, ' ', $e->errorCode ?? $e->type ?? 'error';
} catch (ConnectionException $e) {
// All retry attempts failed, so no HTTP response is available.
echo 'transport error: ', $e->getMessage();
}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 | Área | Códigos |
|---|---|---|
| E01xxx | Infraestrutura | 30 códigos, 2 descontinuados |
| E02xxx | Autenticação e identidade | 9 códigos, 2 descontinuados |
| E03xxx | Cobrança e planos | 12 códigos |
| E04xxx | Envio e entrega de e-mail | 67 códigos, 3 aposentados |
| E05xxx | Domínios e DNS | 19 códigos |
| E06xxx | Webhooks | 7 códigos |
| E07xxx | Wallet | 4 códigos |
| E10xxx | Cotas | 9 códigos, 2 descontinuados |
| E11xxx | Pools de IP e IPs dedicados | 4 códigos, 1 aposentado |
| E12xxx | Envio e entrega SMS | 49 códigos, 5 descontinuados |
| E13xxx | Verify | 7 códigos, 1 aposentado |
| E14xxx | Números | 5 códigos |
| E15xxx | Envio e entrega WhatsApp | 49 códigos |
| E16xxx | Trust | 1 código |
| E17xxx | Caixas de correio de agentes | 14 códigos, 2 aposentados |
| E19xxx | Conformidade de registro | 4 códigos |
| E21xxx | Voz e trunking SIP | 16 códigos, 7 aposentados |
| E22xxx | Consulta de número | 4 códigos |
| E23xxx | Realtime | 1 código |
| E24xxx | Competitive Insights | 6 códigos |
| E25xxx | Sendability | 5 códigos, 1 descontinuado |
| E27xxx | Inbox Insights | 5 códigos |
| E28xxx | Apple Messages for Business | 29 códigos, 2 aposentados |
| E32xxx | Confirmação de operação | 6 códigos |
Relacionados
- Conceitos de erros: estratégia de ramificação, detalhes de validação e semântica de vendor_code
- Autenticação: credenciais por trás de 401 e 403
- Header Idempotency-Key: os erros de conflito 409 e novas tentativas seguras
- Limitação de requisições: políticas, cabeçalhos e como lidar com 429
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 integrationGuia de implementaçãoSend your first email
Obtenha um resumo de implementação