Одна из самых частых проблем в интеграциях — команда видит ошибку при отправке письма, но не знает, что делать дальше: повторять запрос, сообщать пользователю, логировать или считать это критическим сбоем. Поэтому email API должен возвращать не только HTTP-статус, но и понятные поля `ok`, `code` и `message`. Именно `code` должен быть базой для логики обработки ошибок в приложении и AI-агентах.
Типичный пример — `invalid_api_key`. Это не временная ошибка и не повод делать retry. Такая ошибка означает, что ключ отсутствует, передан не в том заголовке или уже невалиден. Корректная реакция — остановить попытку отправки, записать инцидент в лог и уведомить ответственного разработчика или систему управления ключами. Бесконечные повторы в таком случае только засорят журнал и не приведут к отправке.
Другая категория — `invalid_request`. Здесь проблема чаще всего в данных: сломан JSON, отсутствует обязательное поле, неверный формат массива адресатов или некорректное содержимое запроса. Такие ошибки тоже обычно не стоит повторять автоматически, пока приложение или агент не исправят входные данные. Лучший подход — логировать исходный payload в безопасной форме и явно показывать, что запрос был отклонён по вине структуры данных.
Временные ошибки вроде `smtp_unavailable` обрабатываются иначе. Здесь retry уже возможен, но не без ограничений. Для production-интеграций лучше использовать ограниченное число повторных попыток с backoff и обязательной записью результата в лог. Это позволяет не терять письмо из-за кратковременного сбоя, но и не превращать систему в бесконечный цикл повторов. Для AI-агентов особенно важно иметь правила: сколько повторов допустимо и когда надо передавать инцидент человеку.
Хорошая обработка ошибок email API — это всегда сочетание трёх вещей: классификация по `code`, понятные логи и осознанная retry-стратегия. Если внедрить это на старте, интеграция будет гораздо стабильнее и прозрачнее. И наоборот, если игнорировать коды ошибок, даже самый хороший API быстро превратится в источник хаоса в логах и непредсказуемого поведения продукта.