Ограничения числа обращений

Ограничение числа обращений — это количество вызовов API, которое может выполнить приложение или пользователь за определенный промежуток времени. Если превысить это ограничение или ограничения на загрузку ЦП и общее время, для пользователя или приложения может начать действовать регулирование. Дальнейшие запросы к API, выполняемые пользователем или приложением, будут завершаться ошибкой.

Ограничение числа обращений распространяется на все запросы API. Для запросов к Graph API и Instagram Basic Display API действуют ограничения платформы, а для запросов к Marketing API и Graph API для Instagram — ограничения для коммерческих приложений.

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

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

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

Ограничения числа обращений платформы

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

Приложения

Запросы Graph API, для которых используется маркер доступа приложения, учитываются в числе обращений приложения. Количество вызовов приложения — это число вызовов, которые приложение может выполнить в течение скользящего одночасового окна. Оно рассчитывается по следующей формуле:

Значение Number of Users (количество пользователей) рассчитывается на основании количества уникальных активных пользователей приложения за день. Если в какие-то дни активность в приложении невысока (например, пользователи активно обращаются к приложению по выходным, но в течение недели делают это редко), количество пользователей приложения рассчитывается исходя из количества активных пользователей за неделю или за месяц. Приложения с высокой ежедневной вовлеченностью получают более высокие ограничения. Это не зависит от количества установок приложения.

Обратите внимание: это не ограничение числа обращений на пользователя, а ограничение общего количества вызовов, выполняемых вашим приложением. Если общее число обращений из вашего приложения не превышает квоту, любой отдельно взятый пользователь может выполнять более 200 вызовов в час. Например, если у приложения 100 пользователей, оно может делать 20 000 вызовов в час. При этом 19 000 из них может поступать от 10 самых активных пользователей.

Пользователи

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

Обратите внимание: вызовы пользователя могут приходиться на несколько приложений. Например, пользовать может выполнить Х вызовов в приложении 1 и Y вызовов в приложении 2. Если сумма X + Y превысит квоту пользователя, для него начнет действовать ограничение. Это не означает ошибку в приложении. Причиной может быть то, что пользователь работает с несколькими приложениями или неправильно пользуется API.

Заголовки

Конечные точки, к которым приложение отправляет достаточное количество запросов, будут возвращать в ответах HTTP-заголовок X-App-Usage или X-Ad-Account-Usage (для вызовов Ads API версии 3.3 и более ранних). В заголовке будет содержаться строка в формате JSON, в которой указано текущее количество вызовов приложения.

Содержание заголовков

Контент заголовка X-Ad-Account-Usage

Общее время ЦП

Время ЦП, необходимое для обработки запроса. Когда total_cputime достигает 100, вызовы могут начать регулироваться.

Общее время

Время, необходимое для обработки запроса. Когда total_time достигает 100, вызовы могут начать регулироваться.

Пример значения заголовка X-App-Usage

x-app-usage: {
    "call_count": 28,         //Percentage of calls made 
    "total_time": 25,         //Percentage of total time
    "total_cputime": 25       //Percentage of total CPU time
}

Пример значения заголовка X-Ad-Account-Usage

x-ad-account-usage: {
    "acc_id_util_pct": 9.67,   //Percentage of calls made for this ad account.
    "reset_time_duration": 100,   //Time duration (in seconds) it takes to reset the current rate limit score.
    "ads_api_access_tier": 'standard_access'   //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
}

Панель

На Панели приложений отображается количество пользователей приложения, для которых действуют ограничения, текущий процент вызовов приложения по отношению к ограничению числа обращений и средняя активность за последние 7 дней. Чтобы получить сведения об использовании в определенный момент времени, в карточке Ограничение количества обращений на уровне приложения нажмите кнопку Подробнее и наведите курсор на точку на графике. Так как использование зависит от количества вызовов, на графике могут быть представлены данные не за все семь дней. Чем больше вызовов у приложения, тем больше будет показано дней.

Коды ошибок

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

Коды ошибок регулирования

Пример ответа

{
  "error": {
    "message": "(#32) Page request limit reached",
    "type": "OAuthException",
    "code": 32,
    "fbtrace_id": "Fz54k3GZrio"
  }
}

Коды ошибок регулирования, связанные со стабильностью работы платформы Facebook

Рекомендации

• Если приложение исчерпало квоту, прекратите вызовы API. Они будут завершаться ошибкой, но статистика вызовов по-прежнему будет их учитывать, а значит, срок снятия блокировки обращений продлится.
• Чтобы избежать скачков трафика, распределяйте запросы равномерно во времени.
• Используйте фильтры для ограничения размера ответа и избегайте вызовов, которые запрашивают перекрывающиеся данные.
• Чтобы узнать, насколько израсходована квота запросов, посмотрите заголовок HTTP X-App-Usage. Если приложение превысило ограничение, из этого же заголовка можно узнать, когда можно будет вновь совершать вызовы.
• Если регулирование применяется к пользователям, убедитесь, что причина не в вашем приложении. Сократите количество вызовов пользователя или распределите их более равномерно по времени.

Ограничения для коммерческих приложений

Для всех запросов к Marketing API и Pages API, выполняемых с использованием маркера доступа системного пользователя или маркера Страницы, действуют ограничения для коммерческих приложений. Они зависят от того, какие конечные точки вы запрашиваете.

Для Marketing API ограничение числа обращений применяется к рекламному аккаунту в рамках одного сценария использования для коммерческого приложения. Например, для всех конечных точек со сценарием "Управление рекламой" в одном рекламном аккаунте будет действовать общая квота. Если какая-либо конечная точка выполняет много вызовов API, что приводит к ограничениям, другие конечные точки, настроенные в рамках этого же сценария использования, также будут получать сообщения об ошибках, связанных с ограничением числа обращений. Квота зависит от уровня доступа приложения к Marketing API. Стандартный уровень доступа к Marketing API предполагает большие квоты, чем уровень доступа разработчика Marketing API. По умолчанию новое приложение находится на уровне доступа разработчика. Если вам нужно перейти на большую квоту, получите расширенный доступ для стандартного доступа для Ads Management через проверку приложения.

Ads Insights

Запросы, которые выполняет ваше приложение к Ads Insights API, учитываются в метриках ограничения числа обращений, таких как количество вызовов, общее время ЦП и общее время. Количество вызовов приложения определяет, сколько вызовов это приложение может выполнить в течение скользящего одночасового окна. Оно рассчитывается по следующей формуле:

Для приложений со стандартным доступом к функции стандартного доступа для Ads Management:

Для приложений с расширенным доступом к функции стандартного доступа для Ads Management:

Значение Number of Active ads — это количество показываемых в рекламном аккаунте объявлений. Значение User Errors — это количество ошибок, полученных при вызове API. Чтобы увеличить ограничение числа обращений, вы можете запросить стандартный доступ к Ads Management.

Ограничение числа обращений также может зависеть от общего времени работы процессора и фактического общего времени в течение скользящего одночасового окна. Подробнее см. в HTTP-заголовке X-Business-Use-Case: total_cputime и total_time.

Если вы получаете сообщения об ошибках, связанных с ограничением числа обращений, в estimated_time_to_regain_access в заголовке X-Business-Use-Case можно узнать примерное время блокировки.

Ads Management

Запросы, которые ваше приложение выполняет к Ads Management API, учитываются в метриках ограничения числа обращений, таких как количество вызовов, общее время ЦП и общее время. Количество вызовов приложения определяет, сколько вызовов это приложение может выполнить в течение скользящего одночасового окна. Оно рассчитывается по следующей формуле:

Для приложений со стандартным доступом к функции стандартного доступа для Ads Management:

Для приложений с расширенным доступом к функции стандартного доступа для Ads Management:

Значение Number of Active Ads — это количество объявлений для каждого рекламного аккаунта.

Ограничение числа обращений также может зависеть от общего времени работы процессора и фактического общего времени в течение скользящего одночасового окна. Подробнее см. в HTTP-заголовке X-Business-Use-Case: total_cputime и total_time.

Если вы получаете сообщения об ошибках, связанных с ограничением числа обращений, в estimated_time_to_regain_access в заголовке X-Business-Use-Case можно узнать примерное время блокировки.

Каталог

Catalog Batch

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

Значение unique users — это количество уникальных пользователей, выполнивших действия во всех каталогах компании за прошедшие 28 дней. Чем больше пользователи просматривают товары из ваших каталогов, тем больше вызовов выделяется для вас.

Catalog Management

В количество запросов приложения входит количество вызовов, которое ваше приложение может выполнить в течение скользящего одночасового окна для каждого ID каталога. Количество вызовов вычисляется по формуле:

Значение unique users — это количество уникальных пользователей, выполнивших действия во всех каталогах компании за прошедшие 28 дней. Чем больше пользователи просматривают товары из ваших каталогов, тем большее количество вызовов выделяется для вас.

Эта формула применяется к разным конечным точкам каталога.

Дополнительную информацию о текущих ограничениях на использование см. в разделе Заголовки.

Ограничение числа обращений также может зависеть от общего времени работы процессора и фактического общего времени в течение скользящего одночасового окна. Подробнее см. в HTTP-заголовке X-Business-Use-Case: total_cputime и total_time.

Если вы получаете сообщения об ошибках, связанных с ограничением числа обращений, в estimated_time_to_regain_access в заголовке X-Business-Use-Case можно узнать примерное время блокировки.

Пользовательская аудитория

Запросы, которые ваше приложение выполняет к Custom Audience API, учитываются в метриках ограничения числа обращений, таких как количество вызовов, общее время ЦП и общее время. Количество вызовов определяет, сколько вызовов может выполнить приложение в течение скользящего одночасового окна. Оно вычисляется по показанным ниже формулам, но никогда не превышает 700 000.

Для приложений со стандартным доступом к функции стандартного доступа для Ads Management:

Для приложений с расширенным доступом к функции стандартного доступа для Ads Management:

Значение Number of Active Custom Audiences — это количество активных пользовательских аудиторий для каждого рекламного аккаунта.

Ограничение числа обращений также может зависеть от общего времени работы процессора и фактического общего времени в течение скользящего одночасового окна. Подробнее см. в HTTP-заголовке X-Business-Use-Case: total_cputime и total_time.

Если вы получаете сообщения об ошибках, связанных с ограничением числа обращений, в estimated_time_to_regain_access в заголовке X-Business-Use-Case можно узнать примерное время блокировки.

Graph API для Instagram

Вызовы Graph API для Instagram учитываются в количестве вызовов приложения. Количество вызовов приложения уникально для каждой пары приложение-пользователь и соответствует количеству вызовов, выполненных приложением в течение скользящего 24-часового окна. Оно рассчитывается следующим образом:

Значение Number of Impressions — это количество раз, когда любой контент из аккаунта Instagram пользователя приложения отображался на экране других пользователей за последние 24 часа.

Примечания

• Для Instagram Basic Display API действуют ограничения числа обращений платформы.
• Для Business Discovery и Hashtag Search API действуют ограничения платформы.

LeadGen

Запросы к LeadGen API учитываются в количестве вызовов приложения. Количество вызовов приложения определяет, сколько вызовов приложение может выполнить в течение скользящего 24-часового окна.

Значение Leads Generated — это количество лидов, сгенерированных для каждой Страницы этого рекламного аккаунта за последние 90 дней.

Платформа Messenger

Страницы

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

Запросы к Pages API, выполненные с использованием маркера доступа к Странице или маркера системного пользователя, учитываются в количестве вызовов приложения. Количество вызовов приложения определяет, сколько вызовов приложение может выполнить в течение скользящего 24-часового окна:

Значение Number of Engaged Users — это количество пользователей, которые взаимодействовали с вашей Страницей за последние 24 часа.

К запросам Pages API, выполненным с использованием маркера доступа пользователя или приложения, применяется логика ограничений платформы.

Чтобы избежать проблем из-за ограничения числа обращений при использовании функции обращения к общедоступному контенту Страниц, рекомендуется использовать маркер доступа системного пользователя.

Управление эффектами Spark AR Commerce

Запросы к конечным точкам Spark AR Commerce учитываются в количестве вызовов приложения. Количество вызовов приложения определяет, сколько вызовов приложение может выполнить в течение скользящего одночасового окна. Оно рассчитывается по следующей формуле:

Значение Number of Catalogs — это общее количество каталогов во всех аккаунтах для торговли, которыми управляет ваше приложение.

WhatsApp Business Management API

Заголовки

Все ответы API, которые получает ваше приложение и для которых действует ограничение для коммерческих приложений, содержат заголовок HTTP X-Business-Use-Case-Usage (для вызовов Ads API версии 3.3 или более ранней) со строкой в формате JSON. В ней указывается, насколько на текущий момент израсходована квота обращений приложения. Этот заголовок может возвращать до 32 объектов за один вызов.

Содержание заголовка X-Business-Use-Case-Usage

Общее время ЦП

Время ЦП, необходимое для обработки запроса. Когда total_cputime достигает 100, вызовы могут начать регулироваться.

Общее время

Время, необходимое для обработки запроса. Когда total_time достигает 100, вызовы могут начать регулироваться.

Уровень доступа Ads API

Только для типов ads_insights и ads_management. Уровни позволяют вашему приложению получить доступ к Marketing API. По умолчанию приложения находятся на уровне development_access, а Standard_access позволяет уменьшить ограничение числа обращений. Чтобы увеличить ограничение числа обращений и перейти на стандартный уровень, вы можете подать заявку на расширенный доступа к функции Стандартный уровень доступа для управления рекламой.

Пример значения заголовка X-Business-Use-Case-Usage

x-business-use-case-usage: {
    "{business-object-id}": [
        {
            "type": "{rate-limit-type}",           //Type of BUC rate limit logic being applied.
            "call_count": 100,                     //Percentage of calls made. 
            "total_cputime": 25,                   //Percentage of the total CPU time that has been used.
            "total_time": 25,                      //Percentage of the total time that has been used.   
            "estimated_time_to_regain_access": 19,  //Time in minutes to regain access.
            "ads_api_access_tier": "standard_access"  //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
        }
    ],      
    "66782684": [
        {
            "type": "ads_management",
            "call_count": 95,
            "total_cputime": 20,
            "total_time": 20,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access" 
        }
    ],
    "10153848260347724": [
        {
            "type": "ads_insights",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access"
        }
    ],
    "10153848260347724": [
        {
            "type": "pages",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0
        }
    ],
...
}

Коды ошибок

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

Пример сообщения об ошибке

{   
"error": {      
    "message": "(#80001) There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.",      
    "type": "OAuthException",      
    "code": 80001,      
    "fbtrace_id": "AmFGcW_3hwDB7qFbl_QdebZ"   
    }
}

Рекомендации

• Если приложение исчерпало квоту, прекратите вызовы API. Они будут завершаться ошибкой, но по-прежнему будут учитываться в статистике вызовов, а значит, срок снятия блокировки обращений продлится.
• Чтобы узнать, насколько израсходована квота запросов, посмотрите заголовок HTTP X-Business-Use-Case-Usage. Если рекламный аккаунт превысил ограничение, из этого же заголовка можно узнать, когда можно будет вновь выполнять вызовы.
• Проверьте тип регулирования по коду ошибки и конечной точке API.
• Переключитесь на другой рекламный аккаунт, а к этому вернитесь позже.
• Лучше создать новое объявление, чем изменять существующие.
• Во избежание интенсивного трафика равномерно распределяйте запросы между двумя временными интервалами.
• Используйте фильтры, чтобы ограничить размер ответа, и избегайте вызовов, которые запрашивают пересекающиеся данные.

Часто задаваемые вопросы

Что считается вызовом API?

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

Пояснение:

Настоятельно рекомендуем при возможности указывать в одном запросе несколько ID, так как это повышает производительность ответов API.

Я создаю скрапер. Что ещё мне нужно иметь в виду?

Если вы создаете скрапинговый сервис, ознакомьтесь с нашими условиями скрапинга данных.