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
No reintente automáticamente los fallos de autenticación, validación, supresión o conflicto. Un 423 significa que la identidad From exacta está en pausa; detenga ese flujo, corrija sus destinatarios y reintente solo cuando sus métricas móviles se normalicen. Quien llama puede reintentar una respuesta transitoria 429, 502 o 503 con backoff exponencial acotado y jitter. Conserve la misma Idempotency-Key y un payload JSON idéntico al reintentar un mismo envío lógico.
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.