Pour commencer
Erreurs et nouvelles tentatives
Analysez l’enveloppe d’erreur JSON standard et déterminez quand une nouvelle tentative est sûre.
Enveloppe d’erreur
Les échecs de l’API JSON utilisent un unique objet error de premier niveau, avec un message lisible, le status HTTP numérique et un code stable facultatif. Le contrat OpenAPI référence ce schéma pour les échecs attendus comme inattendus.
{
"error": {
"code": "invalid_request",
"message": "A verified From domain is required",
"status": 403
}
}Erreurs client
Corrigez les erreurs de saisie 400 avant de réessayer. Remplacez ou révoquez les identifiants invalides après une 401. Une 402 exige un droit d’accès payant, 403 signale une limite de politique ou d’autorisation, 404 correspond à une ressource introuvable dans le périmètre du tenant, 409 à un conflit d’état ou d’idempotence, 413 à un dépassement des limites de pièces jointes, et 422 couvre les erreurs de validation ou de suppression.
Décider d’une nouvelle tentative
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.
Contexte pour le support
Notez l’heure de la requête, la route, le statut HTTP, l’identifiant de ressource SendHQ et les champs d’erreur non secrets. N’incluez jamais de clé API, de cookie de session, de corps de message ni de liste de destinataires dans un signalement au support.