Start here
Errors and retries
Parse the standard JSON error envelope and decide when a retry is safe.
Error envelope
JSON API failures use one top-level error object with a human-readable message, the numeric HTTP status, and an optional stable code. The OpenAPI contract references this schema for expected and unexpected failures.
{
"error": {
"code": "invalid_request",
"message": "A verified From domain is required",
"status": 403
}
}Client errors
Correct 400 input errors before retrying. Replace or revoke invalid credentials after 401. A 402 requires paid entitlement, 403 marks a policy or permission boundary, 404 is a missing tenant-scoped resource, 409 is a state or idempotency conflict, 413 exceeds attachment limits, and 422 covers validation or suppression.
Retry decisions
Do not automatically retry authentication, validation, suppression, or conflict failures. A 423 means the exact From identity is paused; stop that stream, correct its recipients, and retry only after its rolling metrics clear. A caller may retry a transient 429, 502, or 503 response with bounded exponential backoff and jitter. Preserve the same Idempotency-Key and identical JSON payload when retrying one logical send.
Support context
Record the request time, route, HTTP status, SendHQ resource ID, and non-secret error fields. Never include an API key, session cookie, message body, or recipient list in a support report.