Comece aqui
Erros e novas tentativas
Faça o parsing do envelope de erro JSON padrão e decida quando é seguro tentar novamente.
Envelope de erro
As falhas da API JSON usam um único objeto error de nível superior, com uma message legível por humanos, o status HTTP numérico e um code estável opcional. O contrato OpenAPI referencia este schema para falhas esperadas e inesperadas.
{
"error": {
"code": "invalid_request",
"message": "A verified From domain is required",
"status": 403
}
}Erros do cliente
Corrija os erros de entrada 400 antes de tentar novamente. Substitua ou revogue credenciais inválidas após um 401. Um 402 exige um direito de uso pago, 403 indica um limite de política ou de permissão, 404 é um recurso inexistente no escopo do tenant, 409 é um conflito de estado ou de idempotência, 413 excede os limites de anexos e 422 cobre validação ou supressão.
Quando tentar novamente
Não tente novamente de forma automática falhas de autenticação, validação, supressão ou conflito. Um 423 significa que a identidade From exata está pausada; interrompa esse fluxo, corrija os destinatários e tente novamente só depois que as métricas móveis dela se normalizarem. O chamador pode tentar novamente uma resposta transitória 429, 502 ou 503 com backoff exponencial limitado e jitter. Mantenha a mesma Idempotency-Key e um payload JSON idêntico ao tentar novamente um mesmo envio lógico.
Contexto para o suporte
Registre o horário da requisição, a rota, o status HTTP, o ID do recurso no SendHQ e os campos de erro que não sejam secretos. Nunca inclua chave de API, cookie de sessão, corpo da mensagem ou lista de destinatários em um relato ao suporte.