С чего начать
Ошибки и повторные попытки
Как разбирать стандартную 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 охватывает ошибки валидации и стоп-лист.
Когда повторять запрос
Не повторяйте автоматически запросы, завершившиеся ошибками аутентификации, валидации, стоп-листа или конфликта. 423 означает, что конкретный адрес отправителя From приостановлен: остановите этот поток, исправьте список получателей и повторяйте отправку только после того, как его скользящие метрики придут в норму. Временные ответы 429, 502 или 503 можно повторять с ограниченной экспоненциальной задержкой и случайным разбросом (jitter). При повторе одной логической отправки сохраняйте тот же Idempotency-Key и идентичную JSON-нагрузку.
Данные для поддержки
Запишите время запроса, маршрут, HTTP-статус, ID ресурса SendHQ и несекретные поля ошибки. Никогда не включайте в обращение в поддержку API-ключ, cookie сессии, текст письма или список получателей.