Почему интеграции ломаются: практический разбор API, данных и повторных запросов

Система должна понимать, кто владеет данными, когда отправлять изменение и что считать подтверждением. Простого POST недостаточно, если сеть оборвалась после записи.

Начните с карты событий и объектов: создание, изменение, отмена, повторная отправка и ручное исправление.

Зафиксируйте обязательные поля, форматы дат, идентификаторы, версию схемы и правила несовместимых изменений. Отдельно опишите лимиты, таймауты и поведение при частичном ответе.

Контракт должен быть тестируемым. Пример JSON в документации не заменяет набор проверок на реальные ошибки и пограничные значения.

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

Для долгих операций используйте очередь, статус обработки и понятный способ повторить только неуспешный шаг.

Логи нужны инженеру, но бизнесу нужен статус: что не синхронизировалось, когда будет повтор и какое действие доступно оператору. Метрики задержки, доли ошибок и возраста очереди показывают деградацию до жалобы клиента.

Так интеграция становится управляемой частью продукта, а не невидимым скриптом между системами.

Интеграция ломается, когда две системы считают себя владельцем одного поля, по-разному понимают статус или не умеют отличить повтор от новой операции. До retry и очередей составьте таблицу объектов, событий и источников истины.

Зафиксируйте, кто может исправить данные и как исправление попадёт в соседнюю систему. Ручная коррекция без журнала создаёт расхождение, которое невозможно объяснить через неделю.

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

Не повторяйте вслепую платежи, заказы и уведомления. Разделяйте технический retry, ручную повторную отправку и компенсационную операцию, если внешний сервис уже изменил состояние.

В incident review связывайте входное событие, очередь, запрос во внешний сервис, запись в базе и уведомление пользователю. Correlation ID и структурированные логи должны позволять пройти эту цепочку без догадок.

После исправления добавьте тест на конкретную причину сбоя и метрику, которая покажет повтор раньше клиента. Так каждая ошибка улучшает контракт и наблюдаемость.

Соберите correlation ID, время запроса, попытки повтора, ответ провайдера и запись локального состояния. Последовательность важнее отдельной ошибки: она показывает, где система потеряла подтверждение.

Если логов недостаточно, не включайте без разбора полное тело запросов. Добавьте безопасные поля и маскирование секретов, чтобы диагностика не создала новую проблему.

Таймаут, временная недоступность и rate limit могут требовать backoff. Ошибка валидации, отсутствие права или устаревший идентификатор требуют исправления данных или ручного решения.

Один общий retry для всех кодов приводит к лавине запросов и дубликатам. Политика должна быть частью контракта интеграции и видна в метриках.

Добавьте тест на конкретный сценарий, алерт на ранний сигнал и инструкцию для поддержки. Проверьте, можно ли безопасно повторить незавершённую операцию.

Цель postmortem — не найти виноватого, а сделать следующий сбой короче, понятнее и дешевле.

Соберите цепочку идентификаторов: запрос, сообщение в очереди, ответ партнёра и запись в локальной базе. Сравнивайте время, версию контракта и полезную нагрузку на каждом переходе.

Так становится видно, где данные потерялись, повторились или были приняты с другой семантикой. Простое повторение запроса редко исправляет такую ошибку.

Зафиксируйте реальные инциденты как тестовые сценарии: таймаут, дубликат webhook, частичный ответ, изменение справочника. Прогоняйте их при изменении адаптера или версии API.

Интеграция считается устойчивой, когда команда может доказать, что исправление не вернуло старое расхождение.

Для каждой операции определите ключ повтора и результат повторной доставки. Оператору важно понимать, что заказ уже создан, а не нажимать кнопку ещё раз. Это правило должно быть единым в API, очереди и интерфейсе восстановления.

Одинаковое поле status может означать «принят», «оплачен» или «передан в работу» в разных системах. Составьте таблицу переходов и тестируйте невозможные комбинации. Схема JSON может быть валидной, но бизнес-операция — неверной.

После восстановления сохраните временную шкалу, затронутые операции, сигнал обнаружения и изменение, которое предотвращает повтор. Не ограничивайтесь фразой «перезапустили сервис». Такой отчёт превращает единичную ошибку в улучшение архитектуры и runbook.