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.

Resposta de erro
{
  "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

Do not automatically retry authentication, validation, suppression, conflict, or 402 subscription_required failures. A 402 means the workspace has no active subscription; choose a plan, then send. A 423 with code sender_paused means the exact From identity is paused. A 423 with code account_paused means the workspace is paused for review: the body includes the measured bounce and complaint rates and the limits they crossed (bounce_rate vs bounce_limit, complaint_rate vs complaint_limit). Stop that stream. A 429 with code daily_limit_reached is the workspace daily ladder, not a short backoff. Wait until resets_at (midnight UTC). Retry-After is the seconds until then. hourly_limit_reached waits until the next UTC hour. gmail_recipient_limit waits until midnight UTC. The refused message was not queued. Other 429 responses (quota_exhausted) wait until that monthly, per-sender, or attachment limit resets. A caller may retry a transient 502 or 503 with bounded exponential backoff and jitter. Preserve the same Idempotency-Key and identical JSON payload when retrying one logical send.

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.