Обработка ошибок API и правила повторов

Короткий ответ

Обработка ошибок API начинается с одного вопроса: есть ли смысл повторять эту ошибку? Временные ошибки — ошибки сервера (5xx), тайм-ауты, «слишком много запросов» (429) — повторяются с растущими интервалами. Постоянные — неверный запрос, нет прав, не найдено (большинство 4xx) — не повторяются: повтор не изменит результат, их нужно довести до человека для исправления. У каждого повтора есть лимит, запрос, исчерпавший лимит, не теряется, а попадает в отдельную очередь (dead-letter), а при превышении порога ответственный получает уведомление. Повторы безопасны только вместе с идемпотентностью.

Зачем нужно правило ошибок

Интеграция без правила ведёт себя в одной из двух крайностей. В первой упавший запрос просто исчезает: лид не попадает в CRM, и никто не знает. Во второй система повторяет ошибку мгновенно и без остановки — если другая сторона уже перегружена, повторы окончательно её роняют, а аккаунт может быть заблокирован за превышение лимита запросов.

Правило ошибок — между этими крайностями: что, когда и сколько раз повторять и когда остановиться и сообщить человеку.

Классы ошибок

1. 1Временные: повторятьОшибки сервера (500, 502, 503, 504), тайм-ауты, обрывы сети.
2. 2Лимит: подождать и повторить429 «слишком много запросов» — ждать столько, сколько говорит другая сторона (заголовок Retry-After).
3. 3Постоянные: не повторять400 неверный запрос, 401/403 права, 404 не найдено, 422 не прошла проверка данных.
4. 4Неизвестные: осторожноНеожиданный формат ответа — один-два повтора, затем человек.

Exponential backoff: растущие интервалы

Повторы делаются не через равные, а через растущие интервалы: например, 30 секунд, 2 минуты, 10 минут, 30 минут, 2 часа. Это называется exponential backoff. К интервалам добавляется небольшая случайная величина (jitter), чтобы сотни запросов, упавших одновременно, не вернулись тоже одновременно. Если другая сторона заголовком «Retry-After» говорит, сколько ждать, это время соблюдается.

Лимиты: сколько раз и как долго

• Максимум попыток: например, 5–8.
• Максимальный возраст: если событие старше заданного срока (например, 24 часа), оно больше не отправляется — устаревшие данные могут навредить.
• Бизнес-смысл: уведомление «создан лид» с опозданием на час ещё полезно, а «клиент на линии» — уже нет.
• Запрос, достигший лимита, попадает в очередь dead-letter, а не удаляется.

Очередь dead-letter

Очередь dead-letter — место, где хранятся запросы, исчерпавшие все попытки: с данными каждого запроса, последней ошибкой и историей попыток. Когда ответственный устраняет причину — например, обновляет ключ, — запросы отправляются заново. Если очередь не пустеет и на неё никто не смотрит, это просто более аккуратная форма потери данных, поэтому у очереди должен быть владелец.

Пороги уведомлений

Не каждая ошибка — повод для уведомления, иначе команда привыкает их игнорировать. Практичные пороги: ошибка прав (401/403) — сразу; первый запрос, попавший в dead-letter; доля упавших запросов за последний час превысила заданный процент; другая система совсем не отвечает заданное время. Уведомление уходит конкретному человеку или дежурному, а не в общую группу.

Circuit breaker: защитить другую сторону

Если другая система полностью лежит, повтор каждого запроса нагружает её и во время восстановления. Правило circuit breaker: когда число подряд идущих ошибок превышает порог, отправка временно приостанавливается, запросы ждут в очереди, через некоторое время отправляется один пробный запрос, и после его успеха очередь постепенно разбирается.

Ошибка в AI-диалоге: что слышит клиент

Когда AI вызывает API во время разговора — например, за статусом заказа, — ошибка происходит на глазах у клиента. Повтор здесь должен быть коротким: клиент не будет ждать 30 секунд. Правило записывается заранее: один короткий повтор, затем честный ответ — «сейчас не могу проверить статус, оператор напишет вам в течение 15 минут» — и уведомление оператору. При ошибке AI никогда не должен угадывать статус. Подробности такого дизайна — в статье об интеграции чат-бота через API и webhook.

Повторы и идемпотентность

Тайм-аут — самый трудный случай: запрос, возможно, уже обработан на другой стороне, просто не пришёл ответ. Повтор тогда может создать вторую запись. Поэтому каждая повторяемая операция должна быть идемпотентной — второй запрос с тем же ключом не должен создавать второй результат. Подробно — в статье о дублях данных между системами.

Иллюстративный пример

Это иллюстративный пример. Интеграция учебного центра отправляет лиды в CRM. Однажды утром у API-ключа CRM истекает срок, и все запросы возвращают 401. Интеграция без остановки повторяет ошибку, аккаунт CRM на час блокируется за «слишком много запросов», а лиды теряются.

По новому правилу 401 не повторяется: сразу уходит уведомление в IT, а запросы попадают в dead-letter. После обновления ключа очередь отправляется заново, и ни один лид не теряется.

Типичные ошибки

• Повторять все ошибки одинаково.
• Мгновенные повторы без интервала.
• Бесконечные повторы без лимита.
• На очередь dead-letter никто не смотрит.
• Повторять тайм-ауты без идемпотентности.

Ограничения

Даже лучшее правило повторов не решает долгого сбоя другой стороны — оно лишь гарантирует, что данные не потеряются, а системы не перегрузят друг друга. Цифры (попытки, интервалы, возраст) выбираются под бизнес-процесс и в каждой интеграции могут отличаться. Запишите правила в документ требований — соответствующий раздел показан в статье о требованиях к API-интеграции.

В Vexvon

Vexvon отслеживает статус webhook, приходящих из каналов, — ожидает, обрабатывается, повтор, ошибка и т. д. — и повторно обрабатывает упавшие или зависшие webhook. Для webhook, которые Vexvon отправляет в систему компании, и для API компании, которые вызывает AI, повторы, лимиты и ответ клиенту согласуются вместе в плане интеграции. Подробнее — интеграции.

Следующий шаг

Откройте журнал ошибок своих интеграций за последний месяц и разделите ошибки на четыре класса. Для каждого класса запишите текущее поведение: повторяется ли, сколько раз, кто узнаёт? О повторной отправке webhook — в статье что такое webhook. Другие статьи — в разделе о корпоративной интеграции; правила можно написать вместе во время демо.