Цифровые сервисы: практика

Как проверить лимиты API перед переносом данных в CRM: квоты, ошибки и доплаты

Автор и проверка: Алексей Воронов, редакционный координатор ormobil.com · Факты, документы, риски и применимость · Обновлено: 19 января 2026 г.

Перед переносом данных в CRM нужно не «попробовать выгрузку», а заранее посчитать суточные и минутные квоты API, количество записей, размер пакетов, лимиты на чтение и запись, а также стоимость превышения. Если расчёт

Какие API-лимиты влияют на перенос данных в CRM

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

Главная ошибка — считать только общее число клиентов, сделок или заявок. На практике один объект редко переносится одним запросом. Например, для одной компании могут потребоваться отдельные обращения к API для создания организации, контакта, сделки, примечаний, задач, файлов, пользовательских полей и связей между сущностями. В результате 50 000 клиентов легко превращаются в 300 000–600 000 API-запросов.

Перед стартом нужно проверить минимум семь типов ограничений.

Суточная квота запросов

Суточная квота показывает, сколько обращений к API разрешено за 24 часа. У разных CRM и внешних сервисов это может быть 10 000, 100 000, 500 000 или больше запросов в сутки. Иногда лимит зависит от тарифа, числа пользователей или купленного пакета API.

Если перенос рассчитан на 450 000 запросов, а доступная квота — 100 000 запросов в сутки, миграция физически не завершится за один день без доплаты или смены схемы. В этом случае планируют перенос на 5–6 дней с запасом на ошибки, повторные попытки и контрольные сверки.

Лимит запросов в минуту или секунду

Даже если суточной квоты хватает, перенос может остановиться из-за ограничения частоты. Например, API разрешает 10 запросов в секунду или 600 запросов в минуту. Если скрипт миграции отправляет 50 запросов в секунду, сервис начнёт возвращать HTTP 429 Too Many Requests.

Для миграции важен не максимальный рекламный показатель, а устойчивый режим работы. Если документация допускает 20 запросов в секунду, для безопасного переноса обычно закладывают 50–70% от лимита: 10–14 запросов в секунду. Это снижает риск блокировок, особенно если параллельно CRM используют сотрудники, интеграции телефонии, сайта, чатов и рассылок.

Лимиты на чтение и запись

Некоторые API отдельно ограничивают чтение данных, создание новых объектов, обновление существующих записей и загрузку файлов. Чтение может быть дешёвым и быстрым, а массовая запись — более строгой.

Например:

• чтение клиентов — до 1000 записей за запрос;

• создание сделок — до 100 записей в пакете;

• обновление пользовательских полей — не чаще 5 запросов в секунду;

• загрузка файлов — до 20 МБ на файл и до 2 ГБ в сутки.

Если эти лимиты не разделить, план миграции получится слишком оптимистичным. Особенно часто недооценивают обновление связей: сначала создают контакты и компании, потом сделки, потом связи между ними. Это отдельные операции, а не «одна загрузка базы».

Размер пакета и payload

API может ограничивать не только количество запросов, но и размер тела запроса. Типичные ограничения — 1 МБ, 5 МБ, 10 МБ или 50 МБ на один запрос. Для простых карточек клиента это не проблема, но при переносе истории переписки, комментариев, UTM-меток, вложений и длинных описаний размер быстро растёт.

Если пакет из 500 записей превышает лимит, его придётся делить на 100, 50 или даже 20 записей. Это увеличивает количество запросов и время переноса. Поэтому тестировать нужно не пустые карточки, а реальные данные: записи с длинными комментариями, нестандартными полями, спецсимволами, телефонией, файлами и историей изменений.

Лимиты на массовые операции

Некоторые CRM предоставляют batch API: одним запросом можно отправить пакет операций. Но у batch-методов тоже есть ограничения: например, до 50 операций в одном пакете, до 100 объектов за запрос или до 10 параллельных batch-задач.

Batch ускоряет перенос, но усложняет обработку ошибок. Если из 100 объектов в пакете 7 не прошли валидацию, нужно корректно сохранить результат по каждому объекту, а не повторить весь пакет и создать 93 дубля. Поэтому batch-методы стоит использовать только при наличии журнала соответствий: старый ID → новый ID → статус операции → дата и код ответа.

Ограничения тарифа и доплаты

Лимиты API часто завязаны на тариф. На базовом тарифе может быть ограниченный доступ к API, отсутствовать массовый импорт, быть ниже лимиты на файлы или не поддерживаться webhooks. На расширенном тарифе появляются дополнительные квоты, но увеличивается ежемесячная стоимость.

Перед переносом запросите у поставщика CRM или интегратора три варианта сметы: базовую, оптимальную и срочную. Для тиража или проекта запросите 3 сметы: базовую, оптимальную и срочную; отдельно отметьте сроки 3–7 дней, гарантию и стоимость переделки. В смете должны быть отдельно указаны: подготовка данных, тестовая миграция, основной перенос, проверка, исправление ошибок, поддержка после запуска и возможная доплата за API-пакеты.

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

Ограничения по авторизации и токенам

Перенос может остановиться не из-за квоты, а из-за истечения access token, ограничения refresh token, блокировки IP или неправильных прав приложения. Проверьте:

• срок жизни access token: например, 1 час, 12 часов или 24 часа;

• срок жизни refresh token;

• можно ли обновлять токен без участия пользователя;

• какие scopes нужны для чтения, создания, обновления и удаления данных;

• есть ли ограничение по IP-адресам;

• разрешена ли параллельная работа нескольких процессов миграции.

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

Как посчитать объем миграции и частоту запросов до старта

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

Составьте карту объектов

Минимальный список для CRM-миграции обычно включает:

• компании;

• контакты;

• сделки;

• лиды или заявки;

• задачи;

• звонки;

• письма;

• комментарии;

• файлы;

• статусы воронок;

• пользовательские поля;

• связи между сущностями;

• ответственных сотрудников;

• источники и UTM-метки.

Для каждого типа объекта укажите количество записей и действие: создать, обновить, проверить наличие, связать, прикрепить файл, записать историю. Если нужно исключать дубли, добавляются запросы на поиск существующих записей по телефону, email, ИНН, внешнему ID или другому ключу.

Пример расчёта:

В этом примере предварительный объём — 555 000 запросов. К нему нужно добавить запас на ошибки, повторы и контрольные сверки. Практичный резерв — 15–25%. При резерве 20% итоговый плановый объём составит 666 000 запросов.

Разделите перенос на этапы

Не переносите всё одной очередью. Безопаснее разделить миграцию на этапы:

1. справочники и пользователи;

2. компании;

3. контакты;

4. сделки и лиды;

5. связи между сущностями;

6. задачи и активности;

7. комментарии и история;

8. файлы;

9. контрольная сверка;

10. дозагрузка изменений за период переноса.

Такой порядок позволяет сохранить связи. Например, сделку нельзя корректно связать с компанией, если компания ещё не создана в новой CRM и нет её нового ID. Поэтому нужен журнал соответствий: ID в старой системе, ID в новой CRM, дата операции, статус, код ответа API.

Посчитайте длительность по лимиту частоты

Формула простая:

`время переноса = количество запросов / безопасная частота запросов`

Если нужно выполнить 666 000 запросов, а безопасная частота — 8 запросов в секунду, минимальное техническое время составит:

666 000 / 8 = 83 250 секунд, то есть около 23,1 часа.

Но это только идеальное время. Добавьте:

• 15–25% на повторы после 429 и 5xx;

• 1–2 часа на проверку после каждого крупного этапа;

• окно на заморозку изменений;

• время на исправление данных, не прошедших валидацию;

• резерв на ручные согласования.

В реальном проекте такой перенос лучше планировать не на одну ночь, а на 2–4 рабочих дня или на несколько ночных окон. Для проектов с объёмом до 50 000–100 000 записей часто достаточно 3–7 дней с учётом теста, основной миграции и проверки. Для более крупных баз сроки нужно считать отдельно.

Проверьте суточную квоту

Если у вас 666 000 запросов, а суточная квота — 200 000, перенос займёт минимум 4 суток по квоте, даже если частота запросов позволяет быстрее. Если квота — 1 000 000 запросов в сутки, ограничением станет уже не день, а частота, размер пакетов, файлы или стабильность API.

Важно учитывать рабочую нагрузку CRM. Если в обычный день интеграции сайта, телефонии, склада и рассылок уже используют 60 000 запросов, нельзя отдавать миграции всю суточную квоту. Оставьте рабочий резерв. Например, при квоте 200 000 запросов в сутки и текущей нагрузке 60 000 безопасно выделить миграции не больше 100 000–120 000 запросов в сутки.

Проведите тестовую миграцию на выборке

Тестовая выборка должна быть репрезентативной, а не удобной. Возьмите:

• 100–500 обычных записей;

• 20–50 записей с длинной историей;

• 20 записей с файлами;

• записи с несколькими контактами и компаниями;

• записи со спецсимволами, разными форматами телефонов и email;

• записи с пустыми обязательными полями;

• старые закрытые сделки;

• записи с нестандартными пользовательскими полями.

После теста сравните план с фактом. Если ожидали 3 запроса на сделку, а получилось 6, пересчитайте весь объём. Если 5% записей не проходят из-за обязательных полей, сначала исправьте данные, а не запускайте массовую миграцию.

Таблица проверки квот, ошибок и доплат

Проверьте портфолио, техническое задание, смету, сроки, гарантию, порядок правок, поддержку и документы на материалы или услугу. Для CRM-миграции «материалы» — это выгрузки, схемы полей, таблицы соответствия, файлы, доступы, журналы операций и итоговые отчёты. Если исполнитель не показывает, как будет фиксировать ошибки API и повторные попытки, перенос нельзя считать управляемым.

Отдельно запросите стоимость переделки. Например: что входит в гарантийное исправление, сколько стоит повторная загрузка 10 000 записей, оплачивается ли повторный перенос файлов, кто отвечает за ошибки из-за неверной исходной выгрузки. Это нужно зафиксировать до старта, а не после появления дублей в CRM. При приёмке пригодится логика из разбора о том, как принять работу подрядчика по цифровому проекту: проверять не обещания, а фактические результаты, журналы и согласованные критерии.

Как обработать 429, 5xx, таймауты и повторы без дублей

Ошибки API при переносе неизбежны. Нормальный вопрос не «будут ли ошибки», а «как система поймёт, что уже создано, что нужно повторить, а что нужно исправить вручную».

429 Too Many Requests

Код 429 означает, что лимит частоты или квоты превышен. Скрипт не должен продолжать отправлять запросы с той же скоростью. Правильное поведение:

1. прочитать заголовок Retry-After, если он есть;

2. поставить запрос в очередь ожидания;

3. снизить частоту по этому методу API;

4. повторить запрос после паузы;

5. записать событие в журнал.

Если Retry-After равен 30 секундам, повтор через 1–2 секунды только усилит проблему. Если заголовка нет, используют экспоненциальную задержку: например, 2, 4, 8, 16, 32 секунды с верхним пределом. После 5–7 неудачных попыток запись лучше перевести в статус «требует проверки», а не держать процесс бесконечно.

Ошибки 5xx

Коды 500, 502, 503 и 504 обычно говорят о проблеме на стороне сервиса, шлюза или временной недоступности. Такие ошибки можно повторять, но только при наличии защиты от дублей.

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

• есть ли idempotency key;

• был ли получен новый ID;

• можно ли найти объект по внешнему ID;

• записан ли результат в журнале;

• поддерживает ли API безопасный повтор.

Лучший вариант — передавать внешний идентификатор из старой системы в отдельное поле CRM. Тогда при повторе можно сначала искать запись по этому ID. Если она уже создана, повторное создание не выполняется, а журнал просто обновляется.

Таймауты

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

Настройте разные типы таймаутов:

• connect timeout — например, 5–10 секунд;

• read timeout — например, 30–120 секунд в зависимости от метода;

• общий лимит выполнения операции;

• лимит повторов;

• статус «неизвестно», если результат нельзя подтвердить.

После таймаута нельзя сразу повторять создание без проверки. Сначала ищите объект по внешнему ID, email, телефону, номеру сделки или другому уникальному ключу. Если объект найден, запишите новый ID и продолжайте. Если не найден — повторите создание.

Ошибки 400, 409 и 422

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

Примеры:

• телефон передан строкой с недопустимыми символами;

• дата в формате `31.12.2025`, а API ждёт `2025-12-31`;

• обязательное поле «Ответственный» пустое;

• статус сделки не существует в новой воронке;

• значение пользовательского поля не входит в справочник;

• объект с таким внешним ID уже создан.

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

Защита от дублей

Чтобы повторы не создавали дубли, используйте несколько уровней защиты:

1. внешний ID из старой системы;

2. таблица соответствий старый ID → новый ID;

3. уникальный ключ для проверки: email, телефон, номер клиента, ИНН, номер сделки;

4. idempotency key, если API его поддерживает;

5. отдельный статус для неопределённых операций;

6. запрет на повторное создание, если есть успешная запись в журнале.

Не полагайтесь только на email или телефон. У одного клиента может быть несколько email, у компании — несколько контактов, у сделки — одинаковое название. Внешний ID надёжнее, потому что он однозначно связывает старую и новую запись.

Журнал миграции

Журнал — обязательная часть переноса. В нём должны быть:

• тип объекта;

• старый ID;

• новый ID;

• операция;

• дата и время;

• код ответа API;

• количество попыток;

• текст ошибки;

• статус: создано, обновлено, пропущено, ошибка, требует проверки;

• ссылка на исходные данные или номер строки выгрузки.

Без журнала невозможно доказать, что перенос выполнен корректно. Если через неделю пользователь скажет, что у клиента нет истории звонков, вы должны найти исходную запись, запрос, ответ API и причину: не было данных, API отклонил поле, файл превысил лимит или связь не создалась.

Когда перенос через API лучше отложить или заменить импортом

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

API стоит отложить, если нет технического задания

Типовые риски: нет ТЗ, размытые сроки, устные правки, скрытая стоимость материалов, неподходящий формат файлов или отсутствие поддержки. В CRM-миграции это проявляется быстро: непонятно, какие поля переносить, какие дубли объединять, какие старые статусы сопоставлять с новыми, кто отвечает за ошибки в исходных данных.

До старта должны быть согласованы:

• список сущностей;

• карта полей;

• правила обязательных полей;

• правила дедупликации;

• порядок переноса связей;

• допустимое окно простоя;

• критерии приёмки;

• срок гарантийных исправлений;

• формат отчёта об ошибках.

Если этого нет, API только ускорит хаос. Сначала нужно подготовить данные и схему миграции.

Импорт файлами лучше, если объём небольшой и структура простая

Если нужно перенести 3000 контактов, 500 компаний и 1000 сделок без сложной истории, комментариев и файлов, CSV/XLSX-импорт может быть быстрее и дешевле. Особенно если CRM умеет сопоставлять поля, обновлять существующие записи и показывать ошибки до загрузки.

Файловый импорт подходит, когда:

• данные помещаются в несколько таблиц;

• связи простые и понятные;

• нет необходимости переносить историю действий;

• можно вручную проверить результат;

• нет жёсткого требования к автоматической синхронизации.

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

API нужен, если важны связи, история и дозагрузка изменений

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

В этом случае файл не даст достаточного контроля. Нужны очереди, журналы, повторные попытки, проверка статусов, сопоставление ID и автоматическая сверка.

Перенос стоит остановить, если тест показывает высокий процент ошибок

Если на тестовой выборке 1000 записей 100–150 падают с ошибками валидации, запускать полную миграцию нельзя. Ошибки не исчезнут на большом объёме, а умножатся.

Ориентиры для решения:

• до 1–2% ошибок — можно исправлять точечно;

• 3–5% — нужен отдельный этап очистки данных;

• больше 5–7% — лучше остановить перенос и пересобрать карту полей;

• больше 10% — высок риск, что схема миграции неверная.

Особенно опасны ошибки в ключевых полях: телефоны, email, внешние ID, ответственные, статусы сделок, даты, суммы, связи компания—контакт—сделка. Если они некорректны, новая CRM будет выглядеть заполненной, но работать с ней будет сложно.

Что может пойти не так

Самые частые проблемы при переносе через API:

• API-квота закончилась в середине переноса;

• часть записей создалась, но связи не проставились;

• из-за повторов появились дубли;

• файлы не загрузились из-за размера или формата;

• комментарии потеряли автора или дату;

• сделки попали не в ту воронку;

• старые статусы не сопоставлены с новыми;

• сотрудники продолжили менять данные во время миграции;

• подрядчик не передал журнал операций;

• доплата за API, срочность или переделку появилась после старта;

• поддержка закончилась сразу после подписания акта.

Чтобы снизить риск, фиксируйте не только «перенести CRM», а конкретный результат: сколько объектов, какие поля, какие связи, какие исключения, какие сроки, какие лимиты API, какие действия при ошибках и как проходит приёмка.

Сколько времени занимает перенос CRM через API?

Небольшой перенос может занять 1–2 дня, но рабочий срок для проекта с подготовкой, тестом, основной миграцией и проверкой часто составляет 3–7 дней. Если база большая, есть файлы, история, несколько воронок и строгие API-квоты, срок может увеличиться до 2–4 недель.

Как понять, хватит ли API-квоты?

Посчитайте общее количество запросов: все сущности × операции на каждую сущность + резерв 15–25%. Затем сравните результат с суточной квотой и лимитом запросов в секунду. Если нужно 600 000 запросов, а доступно 150 000 в сутки, перенос займёт минимум 4 дня только по квоте.

Что означает ошибка 429 при переносе?

429 Too Many Requests означает, что скрипт отправляет слишком много запросов или превысил квоту. Нужно снизить частоту, учесть Retry-After, поставить запросы в очередь и повторить позже. Игнорировать 429 нельзя: это приведёт к массовым отказам API.

Можно ли просто повторять все неудачные запросы?

Нет. Запросы на чтение обычно можно повторять безопасно, а создание объектов — только при защите от дублей. После таймаута или 5xx сначала нужно проверить, не был ли объект уже создан. Иначе появятся повторные контакты, компании и сделки.

Какие документы нужны перед миграцией?

Минимум нужны ТЗ, смета, карта полей, правила дедупликации, график переноса, условия поддержки и акт приёмки. Для данных клиентов также могут понадобиться NDA, DPA или другой документ о конфиденциальности и обработке данных.

Когда лучше выбрать импорт CSV или XLSX вместо API?

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

Какой процент ошибок на тесте допустим?

До 1–2% ошибок обычно можно исправлять точечно. Если ошибок 3–5%, нужен отдельный этап очистки данных. Если больше 5–7%, массовый перенос лучше не запускать до пересмотра карты полей и правил валидации.

Что такое журнал соответствий?

Это таблица или база, где фиксируется связь между старой и новой CRM: старый ID, новый ID, тип объекта, статус, код ответа API и дата операции. Без такого журнала сложно проверить перенос, исправить ошибки и избежать дублей при повторных попытках.

Нужно ли переносить все исторические данные?

Не всегда. Иногда выгоднее перенести активные сделки, актуальных клиентов и последние 12–24 месяца истории, а старый архив оставить в выгрузке для чтения. Решение зависит от требований продаж, поддержки, отчётности и стоимости переноса файлов и комментариев.

Кто должен считать лимиты API — заказчик или подрядчик?

Подрядчик должен подготовить расчёт и объяснить ограничения, но заказчик должен его проверить перед согласованием сметы. В расчёте должны быть квоты, частота запросов, объём данных, резерв на повторы, доплаты, сроки, гарантия и правила исправления ошибок.