Система ограничений

┌─────────────────────────────────────────────┐
│            RestrictionManager               │
│  (Coordinator of all types of restrictions) │
└─────┬──────────────┬──────────────┬─────────┘
      │              │              │
      ▼              ▼              ▼
┌──────────┐  ┌────────────┐  ┌─────────────┐
│ Rate     │  │ Operating  │  │ Adaptive    │
│ Limiter  │  │ Limiter    │  │ Delayer     │
└──────────┘  └────────────┘  └─────────────┘

interface ILimiter {
  getTitle(): string
  setConfig(config: any): Promise<void>
  setLogger(logger: LoggerInterface): void
  getLogger(): LoggerInterface
  canProceed(requestId: string, method: string, params?: any): Promise<boolean>
  waitIfNeeded(requestId: string, method: string, params?: any): Promise<number>
  updateStats(requestId: string, method: string, data: any): Promise<void>
  reset(): Promise<void>
  getStats(): Record<string, any>
}

interface RestrictionParams {
  rateLimit?: RateLimitConfig      // Настройки rate limiting
  operatingLimit?: OperatingLimitConfig  // Настройки лимита времени операций
  adaptiveConfig?: AdaptiveConfig  // Настройки адаптивной задержки
  maxRetries?: number              // Максимальное число повторов запроса (по умолчанию: 3). Кроме `batch`-запросов
  retryDelay?: number              // Базовая задержка между повторами в мс (по умолчанию: 1000)
  retryOnNetworkError?: boolean    // Повтор при `NETWORK_ERROR` / `REQUEST_TIMEOUT` (HTTP 408) (по умолчанию: true).
                                   // Установите `false` для неидемпотентных вызовов — см. «Неидемпотентные вызовы» ниже.
  hardErrorCodes?: string[]        // Доп. коды для немедленного выброса (объединяются со встроенным hard-списком).
  softErrorCodes?: string[]        // Доп. коды для возврата как AjaxResult с ошибкой (объединяются со встроенным soft-списком).
}

interface RateLimitConfig {
  burstLimit: number    // Ёмкость бакета (максимальное число одновременных запросов)
  drainRate: number     // Скорость утечки (запросов в секунду)
  adaptiveEnabled: boolean  // Включить адаптивное управление
}

interface OperatingLimitConfig {
  windowMs: number      // Период времени в миллисекундах (по умолчанию: 600000 = 10 минут)
  limitMs: number       // Максимальное время выполнения в миллисекундах (по умолчанию: 480000 = 480 секунд)
  heavyPercent: number  // Порог для уведомлений о тяжёлых запросах (%)
}

interface AdaptiveConfig {
  enabled: boolean        // Включить адаптивные задержки
  thresholdPercent: number // Порог активации (% от operating limit)
  coefficient: number     // Множитель задержки (0.01 = 1% от оставшегося времени блокировки)
  maxDelay: number        // Максимальная задержка в миллисекундах
}

Если operating текущего метода > (limitMs × thresholdPercent / 100):
  Если operating_reset_at > текущее время:
    Задержка = (operating_reset_at - текущее время) × coefficient
  Иначе:
    Задержка = 7000 мс (значение по умолчанию)
  
  Итоговая задержка = min(рассчитанная, maxDelay)

// Определение типа ошибки
#isRateLimitError(error): boolean          // 503 или QUERY_LIMIT_EXCEEDED
#isOperatingLimitError(error): boolean     // 429 или OPERATION_TIME_LIMIT
#isNonRetryableClientError(error): boolean // HTTP 4xx (кроме 429 / 408)
#isNeedThrowError(error): boolean          // Критические ошибки (повтор бессмыслен)

{
  rateLimit: {
    burstLimit: 50,      // 50 одновременных запросов
    drainRate: 2,        // 2 запроса в секунду
    adaptiveEnabled: true
  },
  operatingLimit: {
    windowMs: 600000,    // 10 минут
    limitMs: 480000,     // 480 секунд (8 минут)
    heavyPercent: 80     // Уведомление при 80% использования
  },
  adaptiveConfig: {
    enabled: true,
    thresholdPercent: 80, // Активация при 80% лимита
    coefficient: 0.01,    // 1% от оставшегося времени блокировки
    maxDelay: 7000        // Максимум 7 секунд задержки
  },
  maxRetries: 3,
  retryDelay: 1000,
  retryOnNetworkError: true
}

{
  ...standard,
  rateLimit: {
    burstLimit: 250,     // 250 одновременных запросов
    drainRate: 5,        // 5 запросов в секунду
    adaptiveEnabled: true
  }
}

{
  ...standard,
  rateLimit: {
    burstLimit: 30,
    drainRate: 1,
    adaptiveEnabled: true
  },
  operatingLimit: {
    windowMs: 600_000,
    limitMs: 480_000,
    heavyPercent: 50 // Более высокий порог для уведомлений
  },
  adaptiveConfig: {
    enabled: true,
    thresholdPercent: 50, // Больше порог
    coefficient: 0.015, // Больше пауза
    maxDelay: 10_000 // Макс 10 секунд
  },
  maxRetries: 5 // Больше попыток
}

{
  ...standard,
  adaptiveConfig: {
    enabled: false, // Выключено
    thresholdPercent: 100,
    coefficient: 0.001,
    maxDelay: 480_000
  },
  maxRetries: 1
}

import { ApiVersion } from '@bitrix24/b24jssdk'

// const $b24 = ...

const statsV2 = $b24.getHttpClient(ApiVersion.v2).getStats()
const statsV3 = $b24.getHttpClient(ApiVersion.v3).getStats()

{
  // Общая статистика
  retries: number,                 // Число попыток повтора
  consecutiveErrors: number,       // Последовательные ошибки
  limitHits: number,               // Попадания в лимит
  
  // Rate Limiter
  tokens: number,                  // Текущее число токенов
  burstLimit: number,              // Текущий burst limit
  drainRate: number,               // Текущий drain rate
  
  // Adaptive Delayer
  adaptiveDelays: number,          // Число применённых задержек
  totalAdaptiveDelay: number,      // Суммарное время задержек
  adaptiveDelayAvg: number,        // Средняя задержка
  
  // Operating Limiter
  heavyRequestCount: number,       // Число тяжёлых запросов
  operatingStats: {                // Статистика по методам (в секундах)
    [method: string]: number
  },
  
  // Ошибки по методам
  errorCounts: {
    [method: string]: number
  }
}

// Полный сброс всей статистики лимитера
import { ApiVersion } from '@bitrix24/b24jssdk'

// const $b24 = ...

await $b24.getHttpClient(ApiVersion.v2).reset()
await $b24.getHttpClient(ApiVersion.v3).reset()

import { ApiVersion, ParamsFactory } from '@bitrix24/b24jssdk'

// const $b24 = ...

// 1. Поднимите таймаут, чтобы клиент действительно ждал медленную операцию.
const clientAxios = $b24.getHttpClient(ApiVersion.v2).ajaxClient
clientAxios.defaults.timeout = 120_000 // по умолчанию 30_000

// 2. Отключите повторы на транспортных ошибках, чтобы клиентский таймаут никогда
//    не создавал дубликаты сущностей на сервере.
await $b24.setRestrictionManagerParams({
  ...ParamsFactory.getDefault(),
  retryOnNetworkError: false
})

// Теперь безопасно для неидемпотентных вызовов.
const result = await $b24.actions.v2.call.make({
  method: 'crm.documentgenerator.document.add',
  params: { templateId: 42, entityTypeId: 2, entityId: 6014, values: {} }
})

import { B24Hook, ParamsFactory } from '@bitrix24/b24jssdk'
import { ApiVersion } from '@bitrix24/b24jssdk'

const $b24Strict = B24Hook.fromWebhookUrl(hookUrl, {
  restrictionParams: {
    ...ParamsFactory.getDefault(),
    retryOnNetworkError: false
  }
})
$b24Strict.getHttpClient(ApiVersion.v2).ajaxClient.defaults.timeout = 120_000

await $b24Strict.actions.v2.call.make({ method: 'crm.deal.add', params: {/*…*/} })

import { ParamsFactory } from '@bitrix24/b24jssdk'

await $b24.setRestrictionManagerParams({
  ...ParamsFactory.getDefault(),
  maxRetries: 1
})

import { ParamsFactory } from '@bitrix24/b24jssdk'

// const $b24 = ...

await $b24.setRestrictionManagerParams({
  ...ParamsFactory.getDefault(),

  // Эти будут выброшены сразу вместо повтора:
  hardErrorCodes: [
    'DOCUMENT_GENERATOR_ALREADY_IN_QUEUE', // бизнес-код: не повторять
    'MY_APP_INVALID_PAYLOAD'               // кастомный REST: нужна правка на стороне вызывающего
  ],

  // Эти будут возвращены в AjaxResult вместо выброса:
  softErrorCodes: [
    'MY_APP_VALIDATION_FAILED'             // ожидается в рамках обычного потока
  ]
})

import { RestrictionManager } from '@bitrix24/b24jssdk'

console.log(RestrictionManager.BUILT_IN_HARD_ERROR_CODES)
console.log(RestrictionManager.BUILT_IN_SOFT_ERROR_CODES)

import { ParamsFactory } from '@bitrix24/b24jssdk'

// ⚠️ АНТИ-ПАТТЕРН: общий $b24, параллельные обработчики
// Запрос A — неидемпотентное создание, которое хочет ОТКЛЮЧИТЬ повторы:
await $b24.setRestrictionManagerParams({
  ...ParamsFactory.getDefault(),
  retryOnNetworkError: false
})
await $b24.actions.v2.call.make({
  method: 'crm.deal.add',
  params: { fields: { TITLE: 'Deal A' } }
})

// Запрос B — выполняется параллельно на ТОМ ЖЕ $b24 — теперь ТОЖЕ видит
// retryOnNetworkError: false, хотя никогда об этом не просил. А если
// Запрос B первым вызовет setRestrictionManagerParams, создание из
// Запроса A незаметно выполнится с параметрами B. Побеждает последний
// записавший — глобально.

import { ParamsFactory } from '@bitrix24/b24jssdk'

// const $b24 = ...

// Параметры по умолчанию
$b24.setRestrictionManagerParams( ParamsFactory.getDefault() )

// Пакетная обработка
$b24.setRestrictionManagerParams( ParamsFactory.getBatchProcessing() )

// Real-time
$b24.setRestrictionManagerParams( ParamsFactory.getRealtime() )

// По тарифному плану
$b24.setRestrictionManagerParams( ParamsFactory.fromTariffPlan('enterprise') )

// Динамическое изменение конфигурации
$b24.setRestrictionManagerParams({
  ...ParamsFactory.getDefault(),
  rateLimit: {
    burstLimit: 30,  // Временное снижение при проблемах
    drainRate: 1,
    adaptiveEnabled: true
  }
})