С чего начать

Ошибки и повторные попытки

Как разбирать стандартную JSON-обёртку ошибки и когда повторный запрос безопасен.

Обёртка ошибки

Ошибки JSON API возвращаются в одном объекте верхнего уровня error с понятным человеку message, числовым HTTP-кодом status и необязательным стабильным code. Контракт OpenAPI ссылается на эту схему как для ожидаемых, так и для неожиданных ошибок.

Ответ с ошибкой
{
  "error": {
    "code": "invalid_request",
    "message": "A verified From domain is required",
    "status": 403
  }
}

Ошибки клиента

Исправьте ошибки ввода 400, прежде чем повторять запрос. После 401 замените или отзовите недействительные учётные данные. 402 требует платного доступа, 403 означает границу политики или прав доступа, 404 — отсутствующий ресурс в рамках арендатора, 409 — конфликт состояния или идемпотентности, 413 — превышение лимитов на вложения, а 422 охватывает ошибки валидации и стоп-лист.

Когда повторять запрос

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.

Данные для поддержки

Запишите время запроса, маршрут, HTTP-статус, ID ресурса SendHQ и несекретные поля ошибки. Никогда не включайте в обращение в поддержку API-ключ, cookie сессии, текст письма или список получателей.