← Аналитика / analytics / graphql-api

Ограничение частоты запросов на основе аккаунта

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

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

• Масштабируется вместе с ростом вашей инфраструктуры. Пропускная способность растёт вместе с количеством аккаунтов и зон, которые вы запрашиваете, вместо того чтобы ограничиваться единым лимитом на один токен.
• Более высокие квоты для плана Enterprise. Клиенты с планом Enterprise по умолчанию получают более высокие квоты: 15 rps на аккаунт и 10 rps на зону.
• Простое увеличение лимитов. Нужен больший запас? Свяжитесь с нами, мы сможем увеличить ваши лимиты по мере необходимости.

Отправляйте следующий заголовок HTTP вместе с запросами к существующей конечной точке GraphQL API (https://api.cloudflare.com/client/v4/graphql):

X-Rate-Limit-Type: account-based

URL-адрес конечной точки и учётные данные остаются прежними. Запросы без этого заголовка по-прежнему используют лимиты по умолчанию для каждого пользователя или токена, поэтому переходить на новую схему можно постепенно.

Единственный accounts блок засчитывается как один запрос к указанному аккаунту. Один zones блок засчитывается как один запрос к указанной зоне; если zones блок вложен в accounts блок, он засчитывается вместо этого в счёт этого аккаунта.

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

Большинство запросов работают без изменений. Это касается только запросов, которые выбирают список или диапазон зон вверху (viewer) нужно скорректировать: вложите эти зоны в одну accounts блок. Скорректированные запросы действительны в рамках оба модели ограничения скорости запросов.

Запрос одной зоны (без изменений):

{
  viewer {
    zones(filter: { zoneTag: "<ZONE_TAG>" }) {
      # ...
    }
  }
}

Запрос одного аккаунта (без изменений):

{
  viewer {
    accounts(filter: { accountTag: "<ACCOUNT_TAG>" }) {
      # ...
    }
  }
}

Запрос списка или диапазона зон (вложите их в родительский аккаунт):

# Not supported: a list of zones at the viewer level
{
  viewer {
    zones(filter: { zoneTag_in: ["<ZONE_A>", "<ZONE_B>"] }) {
      # ...
    }
  }
}

# Supported: the same zones nested inside their account
{
  viewer {
    accounts(filter: { accountTag: "<ACCOUNT_TAG>" }) {
      zones(filter: { zoneTag_in: ["<ZONE_A>", "<ZONE_B>"] }) {
        # ...
      }
    }
  }
}

То же самое относится к диапазонным фильтрам, например к zoneTag_gt. Семантика запроса идентична: нужен лишь тег аккаунта, которому принадлежат зоны и который у вас уже есть.

Если вам нужна более высокая пропускная способность на аккаунт или на зону, чем предусмотрена по умолчанию, обратитесь в команду, отвечающую за ваш аккаунт Cloudflare, и запросите повышение лимита для конкретных аккаунтов и зон, которые вы запрашиваете. В этой модели повышение лимита применяется к отдельному ресурсу и вступает в силу быстро, без выпуска новой версии.

Когда лимит превышен, API возвращает ошибку с extensions.code установлено на budget, с указанием аккаунта или зоны, для которых было применено ограничение:

{
  "data": null,
  "errors": [
    {
      "extensions": { "code": "budget", "timestamp": "2026-01-01T01:01:01Z" },
      "message": "Account <ACCOUNT_TAG> has exceeded its rate limit. Please try again after 5 minutes. Refer to this page for more details about rate limits: https://developers.cloudflare.com/analytics/graphql-api/limits/",
      "path": null
    }
  ]
}

Аналогичная ошибка на уровне зоны сообщает Zone <ZONE_TAG> has exceeded its rate limit. Повторите попытку по истечении 5-минутного окна, распределите трафик между ресурсами или запросите более высокий лимит.