Интеграция, которая год проработала без единой правки, ломается не из-за вашего кода. На втором году выходят из строя пять вещей, которые при запуске никто не проверяет: лимит запросов, повторная отправка без ключа идемпотентности, молча изменившийся формат ответа, истёкший ключ доступа и очередь повторов, которая вместо восстановления устраивает шторм.
Масштаб задан чужими правилами. Stripe в рабочем режиме разрешает 100 запросов в секунду на аккаунт и 25 в секунду на отдельный метод, GitHub без авторизации — 60 запросов в час против 5000 с токеном, Telegram отдаёт боту около 30 сообщений в секунду и на следующем десятке возвращает 429. Интеграция, написанная «в среднем по документации», упирается в эти числа при первом же всплеске — и это не ошибка разработчика, а невыученный контракт.
Ниже — пять отказов с симптомами, способами обнаружения и ценой в рублях на одном примере, таблица для сверки и чек-лист из двенадцати вопросов, который стоит прогнать по любой интеграции старше года.
Почему отказ приходит на втором году, а не в первый
Первый год интеграция живёт в узком коридоре: данных мало, рядом автор, каждую ошибку видно вручную. Нагрузка растёт постепенно, и первым делом упираются не в сервер, а в чужие лимиты. Второй год — это когда объём вырос втрое, автор ушёл на другой проект, а документация провайдера обновилась без письма на почту.
Второй механизм — дрейф контракта. Провайдер вправе добавить поле, поменять тип, убрать устаревший параметр. Код, который читает ответ «как получится», продолжает работать и тихо пишет в базу пустоту вместо суммы.
Третий механизм — накопление состояний, которых не бывает на тестовом стенде: просроченные токены, зависшие задачи, дубли. Это не падает сразу, а тлеет месяцами. Устройство самого обмена разобрано в материале API для неразработчика; здесь — о том, что в нём ломается.
Самый дорогой из пяти отказов — не тот, что виден, а тот, что не виден: его обнаруживают по расхождению в отчёте через две недели.
Отказ первый — лимит запросов, который не выглядит как ошибка
429 Too Many Requests — стандартный код, введённый в RFC 6585, и к нему прилагается заголовок Retry-After с указанием, когда повторять (разбор — в документации MDN). Проблема в том, что 429 приходит не всегда: часть провайдеров режет запросы на своей стороне и отдаёт таймаут или пустой список вместо внятной ошибки.
Stripe ограничивает 25 запросами в секунду на отдельный метод и 50 одновременными запросами в работе, а причину отказа отдаёт в заголовке Stripe-Rate-Limited-Reason. GitHub без токена — 60 запросов в час, с токеном — 5000, то есть 1,39 запроса в секунду: цикл, который на тесте проходил за четыре минуты, в продакшене упирается в лимит на второй.
Признак: задание стало длиннее в два-три раза без роста объёма данных. Лечится не паузой «на глаз», а ограничителем темпа в коде и обработкой Retry-After. Тот же приём описан в разборе сценария в no-code: хрупкость появляется там, где нет журнала и предела повторов.
Хуже лимита — его отсутствие в коде: тогда ограничение приходит со стороны провайдера, и вместе с ним приходит блокировка, а не вежливая просьба подождать.
Отказ второй — повтор без ключа идемпотентности
Любой повтор после таймаута — лотерея: дошёл первый запрос до провайдера или нет. Если не дошёл, повтор нужен; если дошёл, повтор создаёт второй заказ, второе списание, второе письмо клиенту.
Решение описано в документации Stripe: у POST-запроса есть заголовок Idempotency-Key, ключ до 255 символов, результат хранится не меньше суток, а повтор с тем же ключом возвращает сохранённый ответ — включая 500-е ошибки. Параметры повторного запроса сравниваются с исходными, и при расхождении возвращается ошибка. Практический вывод: ключ уникален для операции и одинаков для всех её повторов.
Расчёт. Магазин на 1200 заказов в месяц при 3% повторов получает 36 дублей. Разбор одного дубля — возврат, сверка, переписка — около 12 минут, итого 432 минуты, или 7,2 часа в месяц. Дороже времени испорченная история заказов, из которой потом считают повторные продажи.
Дубль опасен не суммой, а тем, что он выглядит как нормальный заказ: попадает в отчёт и завышает продажи.
Отказ третий — контракт ответа изменился молча
Провайдеры редко ломают API намеренно: они добавляют поля, меняют типы и помечают параметры устаревшими. Интеграция, которая берёт первый элемент массива или разбирает ответ регуляркой, ломается на первом же косметическом изменении.
Проверка простая: в коде обмена должен быть явный разбор обязательных полей и отдельная ветка на их отсутствие, а не подстановка null. Ошибка разбора должна попадать в журнал вместе с телом ответа — иначе разбирать инцидент нечем.
Цена: если сумма заказа читается как null и превращается в ноль, товар уходит бесплатно, и узнаёте вы об этом от бухгалтерии, а не от мониторинга.
Молчаливое изменение контракта маскирует и второй отказ: дубли перестают быть видны, потому что перестаёт совпадать идентификатор операции.
Отказ четвёртый — истёкший ключ и тихий 401
Ключи и токены живут ограниченное время. Ответ 401 внутри фоновой очереди не останавливает очередь: задача помечается ошибкой, повторяется, снова получает 401 — и так до исчерпания попыток. Внешне всё работает, просто данные не приходят.
Помогает не повтор, а различение кодов: 401 и 403 повторять бессмысленно, 429 и 5xx — можно, с нарастающей паузой. Смешать их в один «повторять до победного» — самый частый способ получить шторм из следующего раздела.
Если у вас нет отдельного счётчика ошибок авторизации, срок жизни ключа вы узнаете в день, когда он истечёт.
Отказ пятый — повторы, которые превращаются в шторм
Пять попыток с паузами 1, 2, 4, 8 и 16 секунд — это 31 секунда на одну задачу. При сотне зависших задач и одинаковой паузе повторы синхронизируются и бьют в провайдера одной волной, ровно тогда, когда он уже перегружен.
Лечится тремя вещами: предел числа одновременных повторов, случайная добавка к паузе и предохранитель — если ошибок больше порога, обмен останавливается и зовёт человека вместо того, чтобы продолжать долбить.
Пример из рассылок: 4800 подписчиков при лимите 30 сообщений в секунду — это 160 секунд непрерывной отправки. Если включить повторы без предела, каждый 429 добавляет задачу в очередь, и очередь растёт быстрее, чем отправляется.
Шторм почти всегда заканчивается не восстановлением, а блокировкой аккаунта — и тогда простой измеряется днями.
Таблица: пять отказов, симптом, обнаружение и цена
Отказ | Симптом | Как обнаружить | Цена на примере магазина |
|---|---|---|---|
Лимит запросов | Задание идёт в два-три раза дольше | Доля ответов 429 и время выполнения задания | 3 500 ₽ маржи за каждый час без обмена |
Повтор без ключа идемпотентности | Два заказа на один платёж | Сверка по идентификатору операции у провайдера | 7,2 часа ручной работы в месяц |
Смена формата ответа | Пустые поля и нули в суммах | Схема ответа и журнал тела ответа | до 2 800 ₽ за каждый неверно собранный заказ |
Истёкший ключ | 401 в очереди, данные не приходят | Отдельный счётчик 401 и 403 | 5 часов обмена — до 49 000 ₽ выручки |
Шторм повторов | Всплеск запросов, блокировка аккаунта | Число одновременных повторов | сутки простоя — до 168 000 ₽ выручки |
Методика расчёта: 60 заказов в день по 2800 ₽, 12-часовое рабочее окно, маржинальность 25%. Цифры в таблице — арифметика на этих допущениях, а не прогноз: подставьте свои.
Как посчитать цену отказа на своих цифрах
Формула в четыре шага. Дневная выручка = заказы в день × средний чек. Часовая = дневная ÷ длина рабочего окна. Маржа в час = часовая × маржинальность. Потери = часы отказа × доля затронутого потока.
Пример, на котором построена таблица: 60 заказов в день по 2800 ₽ — это 168 000 ₽ в день и 14 000 ₽ в час при 12-часовом окне; при маржинальности 25% час простоя стоит 3500 ₽ маржи. Четыре часа — 56 000 ₽ выручки, пять часов с потерей 70% потока — 49 000 ₽.
Пример для услуг: восемь заявок в неделю по 45 000 ₽ — 360 000 ₽ недельного потока, две потерянные заявки стоят 90 000 ₽, больше годовой подписки на большинство сервисов автоматизации. Починка отдельно: восемь часов разработчика по 2500 ₽ — 20 000 ₽. Методика расчёта потерь подробнее разобрана в материале о цене простоя сайта.
Единственная цифра, которую нельзя посчитать задним числом, — заказы, которые не пришли: в базе их нет, и в отчёте они выглядят как спокойная неделя.
Чек-лист: двенадцать вопросов к интеграции старше года
Есть ли журнал запросов и ответов с телом и идентификатором операции?
Ограничен ли темп запросов в коде, а не в голове разработчика?
Обрабатывается ли Retry-After, или пауза всегда фиксированная?
Есть ли ключ идемпотентности на всех POST, создающих объект?
Различаются ли 401 и 403 (не повторять) и 429 и 5xx (повторять можно)?
Есть ли предел числу повторов и предохранитель на всплеск ошибок?
Проверяется ли схема ответа, или поля читаются как получится?
Что происходит, если обязательное поле пришло пустым — падение или тихий ноль?
Знаете ли вы срок жизни каждого ключа и кто его продлевает?
Есть ли отдельные счётчики ошибок авторизации и ошибок разбора?
Сверяете ли вы количество операций у себя и у провайдера раз в неделю?
Записан ли план отключения: кто и как останавливает обмен, если он вредит?
Если на любые три вопроса ответ «нет» — это не задача на потом, а текущий риск. Начинайте с журнала и идемпотентности: они делают остальные отказы видимыми. И помните, что какие задачи отдавать автоматизации решает цена ошибки, а не желание убрать ручную работу.
Обсуждение
Комментарии
Обсуждение загрузится при приближении к разделу.