Skip to main content
Toda falha é um objeto JSON com um único message. O status HTTP é a parte legível por máquina; a string é para uma pessoa lendo um log.

​
A ordem em que as checagens rodam

Isso decide qual erro você vê quando uma requisição está errada em mais de um jeito, e é a razão de um payload malformado poder voltar como um problema de autenticação.
1

Autenticação

Antes de o corpo ser parseado.
2

Autorização

Lista de IPs permitidos, depois tipo de login.
3

Negociação de conteúdo

O cabeçalho Accept.
4

Parsing

JSON bem formado, depois nomes de campos, depois valores.
5

Regras de negócio

Sender ID, template, crédito, rate limit.
Executado contra um 0.7.3 ao vivo, um corpo impossível de fazer parse sem credenciais retorna o erro de autenticação, não o de parse:
Corrija credenciais antes de depurar um payload. Um 401 ou 403 não diz nada sobre se o resto da sua requisição está certo, porque nada abaixo da autenticação foi executado.

​
Autenticação e autorização

401 significa “você não se identificou”; 403 significa “você se identificou e não foi aceito”. A distinção vale para o seu alerta: um 401 súbito costuma ser um deploy que perdeu uma variável de ambiente, enquanto um 403 súbito costuma ser rotação de senha ou um IP que mudou.
Um caminho desconhecido em /secure/ retorna 401, não 404. A autenticação roda antes do roteamento, então a API não diz a um chamador não autenticado quais endpoints existem. Não use um 404 para sondar disponibilidade de endpoint. Você vai receber 401 seja o que for.

​
Negociação de conteúdo

Omitir Accept totalmente está OK. Enviar Accept: text/plain não, e este é o único erro que uma barra de endereços de navegador produz de forma confiável.

​
Parsing

412 para JSON ruim, não 400. A maioria das APIs usa 400 para os dois, então um cliente que faz branch pelo status vai tratar “seu JSON está quebrado” como uma surpresa em nível de rede. Os dois são permanentes. Não repita nenhum.

​
Regras de negócio

Não existe Retry-After em um 429. Faça backoff no seu próprio ritmo: exponencial, com jitter. Um retry em intervalo fixo em muitos workers os ressincroniza no próximo pico.

​
Qual desses você deve repetir?

Um 500 é seguro para repetir precisamente porque a cobrança é revertida. É uma propriedade deliberada do ingresso, não um acidente: o crédito é reservado antes de enfileirar e devolvido quando o enfileiramento falha, então um retry custa uma mensagem, não duas. Veja Como funciona o faturamento.

​
Relacionados

Visão geral da API REST

O envelope, a autenticação e a regra de nomes de campo.

Enviar uma mensagem

Cada campo, com seu padrão e sua recusa.