Primeros pasos
Errores y reintentos
Interprete el sobre de error JSON estándar y decida cuándo es seguro reintentar.
Sobre de error
Los fallos de la API JSON usan un único objeto error de nivel superior con un message legible por personas, el status HTTP numérico y un code estable opcional. El contrato OpenAPI hace referencia a este esquema para los fallos esperados e inesperados.
{
"error": {
"code": "invalid_request",
"message": "A verified From domain is required",
"status": 403
}
}Errores del cliente
Corrija los errores de entrada 400 antes de reintentar. Sustituya o revoque las credenciales no válidas tras un 401. Un 402 requiere un derecho de uso de pago, 403 indica un límite de política o de permisos, 404 es un recurso inexistente dentro del ámbito del tenant, 409 es un conflicto de estado o de idempotencia, 413 supera los límites de adjuntos y 422 cubre la validación o la supresión.
Decisiones de reintento
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 soporte
Registre la hora de la solicitud, la ruta, el estado HTTP, el ID del recurso de SendHQ y los campos de error no secretos. Nunca incluya una clave de API, una cookie de sesión, el cuerpo de un mensaje ni una lista de destinatarios en un informe para soporte.