Erros, e o que fazer com cada um

Todas as respostas de erro têm a mesma forma:

{ "message": "O domínio mail.empresa.pt ainda não está verificado." }

Os erros de validação trazem também os campos:

{
  "message": "The given data was invalid.",
  "errors": {
    "to": ["Indica o destinatário."]
  }
}

A frase pode mudar de língua conforme o cabeçalho Accept-Language. O código de estado e os nomes dos campos nunca mudam, e é sobre esses que se programa.

401 · Não autenticado

Um erro de copiar e colar apanha muita gente: um espaço no fim da chave, ou a chave posta no sítio do utilizador em vez da password no SMTP.

403 · Proibido

404 · Não encontrado

Uma mensagem, um domínio ou um webhook que não existe nesta conta. Uma chamada com um identificador de outra conta também dá 404, e não 403: quem pergunta não tem o direito de ficar a saber que aquele identificador existe.

422 · O pedido não pode ser cumprido

O mais comum, e o mais informativo.

O 422 por supressão não é uma falha da tua integração: é o sistema a impedir um envio que ia devolver outra vez. Trata-o como um resultado.

429 · Pedidos a mais

Duas coisas diferentes dão 429, e o cabeçalho Retry-After distingue-as pelo tamanho: segundos é o limite de pedidos da chave, 600 por minuto; minutos ou horas é a quota da conta, por hora ou por dia.

Em qualquer dos casos espera o que o Retry-After diz e repete. Abrir mais ligações em paralelo piora, porque o limite da chave é por minuto e a quota é da conta inteira: mais ligações gastam a mesma conta mais depressa.

Não é preciso chegar aqui para saber onde estás: cada 202 traz X-CConnect-Quota-Remaining, e o resumo do painel mostra as duas janelas. Ver Enviar pela API.

Nada foi escrito e nada foi enviado. Um 429 não deixa mensagem nenhuma para trás.

503 · Serviço indisponível

Duas situações, ambas temporárias, ambas com Retry-After.

Na verificação de domínio quer dizer uma coisa muito concreta: não conseguimos consultar o DNS agora. Não quer dizer que os registos não estejam publicados.

É por isso que é 503 e não 200 com os registos a zero: um cliente que recebesse 200 iria republicar registos que já estavam correctos.

No envio quer dizer que a plataforma não consegue transportar a mensagem neste momento: ou nenhuma saída serve o teu domínio, ou o conjunto de IPs por onde ele sai já entregou o que podia hoje, ou há mais mensagens em fila do que as que saem. Preferimos dizê-lo à porta: a alternativa era aceitar com 202 e a mensagem ficar dias parada sem ninguém saber.

5xx · Nosso

Repete com espera crescente. Se persistir, fala connosco com o identificador da mensagem ou a hora do pedido.

Códigos SMTP, na submissão

O que repetir e o que não

• Repete: 429, 5xx, 503.
• Não repitas: 401, 403, 404, 422. O pedido é o mesmo e a resposta vai ser a mesma.
• Cuidado com o 202: repetir um pedido que já foi aceite envia uma segunda mensagem. Guarda o id antes de decidir.