Лимиты API и ошибка 429: как передать записи в CRM без потерь

Стандарт HTTP описывает 429 Too Many Requests как превышение допустимого числа запросов за определённый период. Ответ может содержать Retry-After с указанием ожидания. При этом сам стандарт не задаёт универсальный способ подсчёта или идентификации клиента: реальные ограничения необходимо читать в документации конкретного провайдера.

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

Отделяйте ограничение частоты от неверных данных, отсутствия прав и сетевого тайм-аута. Бесконечный повтор некорректного запроса не исправит обязательное поле. А тайм-аут после отправки не доказывает, что операция не выполнена: прежде чем создавать новый объект, нужен предусмотренный контрактом способ проверить результат или безопасно повторить исходное действие.

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

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

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

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

При наличии Retry-After соблюдайте указанное ожидание. Заголовок может содержать число секунд или HTTP-дату; обработчик должен понимать поддерживаемый провайдером формат. Если заголовка нет, применяйте документированную стратегию повторов, например увеличение интервалов с небольшой случайной добавкой, чтобы несколько процессов не возобновляли поток одновременно.

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

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

Документация Microsoft Graph рекомендует использовать Retry-After, а при его отсутствии для соответствующих сценариев описывает экспоненциальное ожидание. Это пример подхода конкретного сервиса. Для CRM и платёжных API условия повторов, допустимые операции и предельные сроки нужно проверить отдельно.

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

Можно ли объединять несколько обновлений одной брони? Иногда можно передавать последнее состояние вместо промежуточных снимков. Но финансовые операции, история событий и зависимые действия не должны исчезать при таком объединении. Правило определяется смыслом операции, а не удобством очереди.

Нужно ли показывать клиенту ошибку CRM? Не обязательно, если бронь уже надёжно подтверждена в основной системе. Сотрудник видит задержку синхронизации, а клиент получает правдивый статус своего заказа. Если внешняя операция обязательна для подтверждения, интерфейс должен явно сохранять промежуточное состояние.