CRM API: ошибки и лимиты
Ошибки и request ID
Ошибки имеют единый envelope:
{
"error": {
"code": "version_conflict",
"message": "Ресурс был изменён другим участником",
"details": { "currentVersion": 8 },
"requestId": "06aa869a-74ea-4184-b1cf-c3d12de6ef7f"
}
}| HTTP | Code | Значение |
|---|---|---|
400 | validation_error, invalid_cursor | Неверный DTO, query, неизвестное поле или cursor |
401 | invalid_token | Токен неверен, истёк, отозван или запрос пришёл вне CIDR allowlist |
403 | insufficient_scope | Не хватает обязательного scope |
404 | not_found | Ресурс не найден в организации токена |
409 | version_conflict | CAS-конфликт; актуальная версия находится в details.currentVersion |
409 | idempotency_conflict, idempotency_in_progress | Конфликт ключа идемпотентности |
409 | crm_provider_not_supported | Организация использует неподдерживаемый внешний CRM-провайдер |
410 | cursor_expired, external_reference_deleted | Нужна полная синхронизация или новый externalId |
413 | payload_too_large | Тело запроса превышает лимит CRM API |
422 | validation_error | Нарушено доменное ограничение |
428 | precondition_required | В upsert существующего mapping отсутствует expectedVersion |
429 | rate_limit_exceeded | Превышен rate limit |
503 | rate_limiter_unavailable | Проверка rate limit недоступна; запрос не выполняется |
Передавайте собственный безопасный X-Request-Id длиной до 128 символов или сохраняйте выданный
сервером заголовок X-Request-Id для диагностики.
Rate limits
Лимиты считаются отдельно для каждого applicationId в минутных окнах:
GETиHEAD: 600 запросов в минуту;- POST, PATCH и DELETE: 120 запросов в минуту.
Отдельно ограничены неудачные попытки аутентификации: 30 в минуту с одного IP. При превышении
ответ 429 приходит вместо 401 и не сообщает, был ли токен близок к верному.
После успешной авторизации и проверки CRM-провайдера rate-limit guard добавляет
RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset; последний — число секунд до сброса
окна. При 429 дополнительно приходит Retry-After. Соблюдайте этот заголовок, используйте
exponential backoff с jitter и ограничивайте параллелизм batch-запросов.
Актуальные значения всех лимитов отдаёт GET /capabilities в полях rateLimits и limits —
они берутся из тех же констант, что применяет сервер, поэтому не расходятся с поведением.
Совместимость и вывод из эксплуатации
Ломающие изменения внутри v1 запрещены: удаление поля или маршрута требует новой major-версии API.
Маршрут, который планируется вывести, заранее начинает отдавать заголовки Deprecation и Sunset
с датами, а при наличии замены — Link с rel="successor-version". Между Deprecation и Sunset
проходит не менее шести месяцев. Проверяйте эти заголовки в интеграции: их появление означает, что
маршрут перестанет работать в указанную дату.
Зарезервировано, но не опубликовано в v1
Публичный API v1 не открывает управление сотрудниками, CRM-правами, API-приложениями и подписками на webhooks, а также чаты и сообщения. Всё это остаётся в защищённом кабинете: API-токены, Webhooks, Сотрудники. Не стройте интеграцию на предполагаемых путях: появление маршрута будет отражено в OpenAPI и этой документации.