Rate limit

Un rate limiting è il numero di chiamate API che un'app o un utente può effettuare in un determinato periodo di tempo. Se questo limite viene superato o se vengono superati i limiti di tempo CPU o totale, l'app o l'utente potrebbero essere sottoposti a throttling. Le richieste API effettuate da un utente o un'app in throttling non avranno esito positivo.

Tutte le richieste API sono soggette a rate limiting. Le richieste API Graph e API Instagram Basic Display sono soggette ai rate limiting della piattaforma, mentre le richieste API Marketing e API Instagram Graph sono soggette ai rate limiting del caso d'uso aziendale (BUC).

Le richieste API Pages sono soggette ai rate limiting BUC o della piattaforma, a seconda del token utilizzato nella richiesta; le richieste effettuate con token d'accesso dell'app o token d'accesso dell'utente sono soggette ai rate limiting della piattaforma, mentre le richieste effettuate con token d'accesso dell'utente di sistema o tokena d'accesso della Pagina sono soggette ai rate limiting del caso d'uso aziendale.

Le statistiche di utilizzo dei rate limiting in tempo reale sono descritte nelle intestazioni incluse nella maggior parte delle risposte API dopo che è stato effettuato un numero sufficiente di chiamate a un endpoint. Le statistiche di utilizzo sui rate limiting della piattaforma sono visualizzate anche nella Dashboard gestione app. Una volta raggiunto un rate limiting, tutte le richieste successive effettuate dall'app non andranno a buon fine e l'API restituirà un codice di errore fino a quando non sarà trascorso un tempo sufficiente affinché il conteggio delle chiamate scenda al di sotto del limite.

Se a una richiesta è possibile applicare sia i rate limiting della piattaforma che quelli del caso d'uso aziendale, verranno applicati i rate limiting BUC.

Rate limiting della piattaforma

I rate limiting della piattaforma vengono tracciati a livello di singola app o a livello di utente, a seconda del tipo di token utilizzato nella richiesta.

App

Le richieste all'API Graph effettuate con un token d'accesso dell'app vengono conteggiate nel calcolo del rate limiting di tale app. Il numero delle chiamate di un'app corrisponde al numero di chiamate che è possibile effettuare durante un periodo continuo di un'ora e viene calcolato come segue:

Calls within one hour = 200 * Number of Users

Il numero di utenti (Number of Users) si basa sul numero di utenti attivi al giorno unici di un'app. Nei casi in cui ci sono periodi lenti di utilizzo giornaliero, come ad esempio se l'app ha un'alta attività nei fine settimana ma una bassa attività nei giorni feriali, per calcolare il numero di utenti dell'app vengono utilizzati gli utenti attivi settimanali e mensili. Le app con un livello elevato di interazione giornaliera avranno rate limiting superiori rispetto alle app con un'interazione giornaliera bassa, indipendentemente dal numero effettivo di installazioni dell'app.

Questo non è un limite per utente, ma un limite per le chiamate effettuate dalla tua app. Ogni singolo utente può effettuare più di 200 chiamate all'ora usando la tua app, a condizione che le chiamate totali dalla tua app non superino il massimo dell'app. Ad esempio, se la tua app ha 100 utenti, può effettuare 20 000 chiamate all'ora. Tuttavia, i dieci utenti con interazione più elevata potrebbero fare 19 000 chiamate.

Utenti

Le richieste API Graph effettuate con un token d'accesso dell'utente vengono considerate nel conteggio delle chiamate dell'utente specifico. Il conteggio delle chiamate di un utente è il numero di chiamate che un utente può effettuare durante un periodo continuo di un'ora. Per motivi di privacy, non riveliamo i valori effettivi del conteggio delle chiamate per gli utenti.

Tieni presente che il conteggio delle chiamate di un utente può essere suddiviso su più app. Ad esempio, un utente potrebbe effettuare X chiamate tramite App1 e Y tramite App2. Se X+Y supera il conteggio delle chiamate dell'utente, a quest'ultimo saranno applicate le limitazioni del rate limiting. Questo non significa necessariamente che un'app stia facendo qualcosa di sbagliato; è possibile che l'utente stia utilizzando più app o usi impropriamente l'API.

Intestazioni

Gli endpoint che ricevono richieste sufficienti dalla tua app includeranno un'intestazione HTTP X-App-Usage o X-Ad-Account-Usage (per chiamate API Ads versione 3.3 e precedenti) nelle risposte. L'intestazione conterrà una stringa in formato JSON che descrive l'utilizzo del rate limiting dell'app corrente.

Contenuto dell'intestazione

Chiave	Descrizione del valore
`call_count`	Un numero intero che esprime la percentuale di chiamate effettuate dalla tua app nell'arco di un periodo continuo di un'ora.
`total_cputime`	Un numero intero che esprime la percentuale di tempo della CPU assegnato per l'elaborazione delle query.
`total_time`	Un numero intero che esprime la percentuale del tempo totale assegnato per l'elaborazione delle query.

Contenuti dell'intestazione X-Ad-Account-Usage

Chiave	Descrizione del valore
`acc_id_util_pct`	La percentuale di chiamate effettuate per questo account pubblicitario prima del raggiungimento del rate limiting.
`reset_time_duration`	Durata del tempo (in secondi) necessario per resettare il rate limiting attuale a 0.
`ads_api_access_tier`	I livelli consentono alla tua app di accedere all'API Marketing. Per impostazione predefinita, le app sono nel livello `development_access`. `Standard_access` consente un rate limiting inferiore. Per ottenere un rate limiting più alto e arrivare al livello standard, puoi richiedere l'"accesso avanzato" alla funzione Accesso standard a Gestione inserzioni.

Tempo di esecuzione totale

La quantità di tempo di esecuzione necessario per l'elaborazione della richiesta. Quando total_cputime raggiunge 100, le chiamate potrebbero essere sottoposte a throttling.

Tempo totale

Il tempo impiegato per l'elaborazione della richiesta. Quando total_time raggiunge 100, le chiamate potrebbero essere sottoposte a throttling.

Valore dell'intestazione X-App-Usage di esempio

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
}

Valore dell'intestazione X-Ad-Account-Usage di esempio

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.
}

Dashboard

La Dashboard gestione app visualizza il numero di utenti dell'app con rate limiting, l'attuale percentuale di utilizzo dei rate limiting dell'app e visualizza l'attività media degli ultimi 7 giorni. Nella scheda Rate limiting dell'app, clicca su Visualizza i dettagli e posiziona il cursore su qualsiasi punto del grafico per visualizzare ulteriori dettagli sull'utilizzo per quel particolare momento. Poiché l'utilizzo dipende dal volume delle chiamate, questo grafico potrebbe non mostrare 7 giorni completi. Le app con un volume più alto di chiamate mostreranno più giorni.

Codici di errore

Quando un'app o un utente ha raggiunto il rate limiting, le richieste effettuate da tale app o utente non andranno a buon fine e l'API risponderà con un codice di errore.

Codici di errore throttling

Codice di errore	Descrizione
`4`	Indica che l'app il cui token viene utilizzato nella richiesta ha raggiunto il rate limiting.
`17`	Indica che l'utente il cui token viene utilizzato nella richiesta ha raggiunto il rate limiting.
`17 with subcode 2446079`	Indica che il token utilizzato nell'API Ads versione 3.3 o precedente ha raggiunto il rate limiting.
`32`	Indica che l'utente o l'app il cui token viene utilizzato nella richiesta API Pages ha raggiunto il rate limiting.
`613`	Indica che è stato raggiunto un rate limiting personalizzato. Per risolvere il problema, consulta i documenti di supporto per l'API specifica che stai chiamando per verificare i rate limiting personalizzati che potrebbero essere applicati.
`613 with subcode 1996`	Indica che abbiamo notato un comportamento incoerente nel volume di richieste all'API della tua app. Se hai apportato modifiche recenti che influiscono sul numero di richieste API, potresti riscontrare questo errore.

Esempio di risposta

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

Codici throttling di stabilità di Facebook

Codice di errore Descrizione

Codice di errore	Descrizione
`throttled`	Se la query è in throttling o meno. Valori: `True`, `False`
`backend_qps`	Primo fattore di throttling `backend_qps`. Valori supportati: `actual_score`: `backend_qps` effettivo di questa app. Valore: `8` `limit`: limite `backend_qps` di questa app. Valore: `5` `more_info`: le query richiedono un numero elevato di richieste backend da gestire. Ti suggeriamo di inviare un numero minore di query o di semplificarle con intervalli di tempo più brevi, meno ID oggetto e così via.
`complexity_score`	Secondo fattore di throttling `complexity_score`. Valori supportati: `actual_score`: `complexity_score` effettivo di questa app. Valore: `0.1` `limit`: limite `complexity_score` di questa app. Valore: `0.01` `more_info`: un `complexity_score` elevato indica che le query sono molto complesse e richiedono una notevole quantità di dati. Ti suggeriamo di semplificare le query con intervalli di tempo più brevi, un numero minore di ID oggetto, metriche o dettagli e così via. Suddividi le query complesse di grandi dimensioni in una serie di query più piccole e distanziale.

throttled

Se la query è in throttling o meno. Valori: True, False

backend_qps

Primo fattore di throttling backend_qps. Valori supportati:

actual_score: backend_qps effettivo di questa app. Valore: 8
limit: limite backend_qps di questa app. Valore: 5
more_info: le query richiedono un numero elevato di richieste backend da gestire. Ti suggeriamo di inviare un numero minore di query o di semplificarle con intervalli di tempo più brevi, meno ID oggetto e così via.

complexity_score

Secondo fattore di throttling complexity_score. Valori supportati:

actual_score: complexity_score effettivo di questa app. Valore: 0.1
limit: limite complexity_score di questa app. Valore: 0.01
more_info: un complexity_score elevato indica che le query sono molto complesse e richiedono una notevole quantità di dati. Ti suggeriamo di semplificare le query con intervalli di tempo più brevi, un numero minore di ID oggetto, metriche o dettagli e così via. Suddividi le query complesse di grandi dimensioni in una serie di query più piccole e distanziale.

Best practice

Quando il limite è stato raggiunto, non effettuare più chiamate API. Continuando a effettuare chiamate continuerai a farle crescere di numero, aumentando il tempo necessario prima che le chiamate tornino a essere eseguite correttamente.
Distribuisci le query in modo uniforme per evitare picchi di traffico.
Usa i filtri per limitare le dimensioni delle risposte dei dati ed evita chiamate che richiedano dati sovrapposti.
Controlla l'intestazione HTTP X-App-Usage per vedere quanto la tua app è vicina al limite e quando puoi riprendere a effettuare chiamate quando il limite sarà stato raggiunto.
Se gli utenti sono in throttling, assicurati che l'app non sia la causa. Riduci le chiamate dell'utente o distribuisci le chiamate dell'utente in modo più uniforme nel tempo.

Rate limiting per casi d'uso aziendali

Tutte le richieste dell'API Marketing e le richieste dell'API Pages effettuate con un token d'accesso di sistema o della Pagina sono soggette ai rate limit dei casi d'uso aziendali (BUC) e dipendono dagli endpoint che stai interrogando.

Per l'API Marketing, il rate limiting è applicato all'account pubblicitario nello stesso caso d'uso aziendale. Ad esempio, tutti gli endpoint con il caso d'uso aziendale Gestione inserzioni condividono la quota totale all'interno dello stesso account pubblicitario. Se un endpoint specifico effettua molte richieste API causando throttling, gli altri endpoint configurati con lo stesso caso d'uso aziendale riceveranno anche errori di rate limiting. La quota dipende dal livello di accesso dell'API Marketing. Il livello di accesso standard dell'API Marketing avrà più quote del livello di accesso di sviluppo. Per impostazione predefinita, le nuove app devono avere il livello di sviluppo. Se hai bisogno di un upgrade per ulteriori quote di rate limiting, esegui l'upgrade della funzione Accesso standard a Gestione inserzioni al livello avanzato nell'analisi dell'app.

Insight sulle inserzioni
Gestione delle inserzioni
Catalogo
Pubblico personalizzato
Piattaforma Instagram
Generazione di contatti

Messenger
Pagine
Gestione dell'effetto Commerce di Spark AR
API Business Management di WhatsApp

Insight sulle inserzioni

Le richieste effettuate dalla tua app all'API Ads Insights vengono conteggiate nelle metriche di rate limiting dell'app, come ad esempio le chiamate totali, il tempo di esecuzione totale e il tempo totale. Il numero delle chiamate di un'app corrisponde al numero di chiamate che è possibile effettuare durante un periodo continuo di un'ora e viene calcolato come segue:

Per le app con accesso standard alla funzione Accesso standard a Gestione inserzioni:

Calls within one hour = 600 + 400 * Number of Active ads - 0.001 * User Errors

Per le app con accesso avanzato alla funzione Accesso standard a Gestione inserzioni:

Calls within one hour = 190000 + 400 * Number of Active ads - 0.001 * User Errors

Il numero di inserzioni attive (Number of Active ads) è il numero di inserzioni attualmente in esecuzione per account pubblicitario. Gli errori sugli utenti (User Errors) indicano il numero di errori ricevuti durante la chiamata API. Per ottenere un rate limiting maggiore, puoi richiedere la funzione Accesso standard a Gestione inserzioni.

Il rate limiting può essere soggetto anche al tempo di esecuzione totale e al wall time totale durante un periodo continuo di un'ora. Per ulteriori dettagli, controlla i valori dell'intestazione HTTP X-Business-Use-Casetotal_cputime e total_time.

Se stai ricevendo errori di rate limiting, puoi anche fare riferimento al parametro estimated_time_to_regain_access nell'intestazione X-Business-Use-Case per il tempo di blocco stimato.

Gestione delle inserzioni

Le richieste effettuate dalla tua app all'API Ads Management sono conteggiate nelle metriche di rate limiting dell'app, come le chiamate totali, il tempo di esecuzione totale e il tempo totale. Il numero delle chiamate di un'app corrisponde al numero di chiamate che è possibile effettuare durante un periodo continuo di un'ora e viene calcolato come segue:

Per le app con accesso standard alla funzione Accesso standard a Gestione inserzioni:

Calls within one hour = 300 + 40 * Number of Active ads

Per le app con accesso avanzato alla funzione Accesso standard a Gestione inserzioni:

Calls within one hour = 100000 + 40 * Number of Active ads

Il numero di inserzioni attive è il numero di inserzioni per ciascun account pubblicitario.

Se stai ricevendo errori di rate limiting, puoi anche fare riferimento al parametro estimated_time_to_regain_access nell'intestazione X-Business-Use-Case per il tempo di blocco stimato.

Catalogo

Batch catalogo

Le richieste effettuate dalla tua app vengono conteggiate nelle metriche di rate limiting come le chiamate totali, il tempo di esecuzione totale e il tempo totale che la tua app può effettuare in un periodo continuo di un'ora per ogni ID del catalogo, calcolato nel modo seguente:

Calls within one hour = 200 + 200 * log2(unique users)

Gli utenti unici (unique users) sono il numero di utenti unici dell'azienda (in tutti i cataloghi) con intenzione negli ultimi 28 giorni. Più utenti visualizzano i prodotti dei tuoi cataloghi, più quote di chiamata vengono assegnate.

Tipo di chiamata	Endpoint
POST	/{catalog_id}/items_batch
POST	/{catalog_id}/localized_items_batch
POST	/{catalog_id}/batch

Gestione del catalogo

Le richieste effettuate dalla tua app vengono conteggiate nel numero di chiamate che l'app può effettuare in un periodo continuo di un'ora per ogni ID del catalogo, calcolato nel modo seguente:

Calls within one hour = 20,000 + 20,000 * log2(unique users)

Questa formula viene applicata a diversi endpoint del catalogo.

Per maggiori informazioni su come ottenere l'utilizzo dei tassi attuali, consulta Intestazioni.

Se stai ricevendo errori di rate limiting, puoi anche fare riferimento al parametro estimated_time_to_regain_access nell'intestazione X-Business-Use-Case per il tempo di blocco stimato.

Pubblico personalizzato

Le richieste effettuate dalla tua app all'API Custom Audience sono conteggiate nelle metriche di rate limiting dell'app, come le chiamate totali, il tempo di esecuzione totale e il tempo totale. Il numero delle chiamate di un'app corrisponde al numero di chiamate che l'app può effettuare durante un periodo continuo di un'ora e viene calcolato come segue, ma non supererà mai 700 000:

Per le app con accesso standard alla funzione Accesso standard a Gestione inserzioni:

Calls within one hour = 5000 + 40 * Number of Active Custom Audiences

Per le app con accesso avanzato alla funzione Accesso standard a Gestione inserzioni:

Calls within one hour = 190000 + 40 * Number of Active Custom Audiences

Il numero di gruppi di pubblico personalizzato attivi (Number of Active Custom Audiences) indica il numero di gruppi di pubblico personalizzato attivi per ciascun account pubblicitario.

Se stai ricevendo errori di rate limiting, puoi anche fare riferimento al parametro estimated_time_to_regain_access nell'intestazione X-Business-Use-Case per il tempo di blocco stimato.

Piattaforma Instagram

Calls to the Instagram Platform endpoints, excluding messaging, are counted against the calling app's call count. An app's call count is unique for each app and app user pair, and is the number of calls the app has made in a rolling 24 hour window. It is calculated as follows:

Calls within 24 hours = 4800 * Number of Impressions

The Number of Impressions is the number of times any content from the app user's Instagram professional account has entered a person's screen within the last 24 hours.

Notes

The Instagram Basic Display API uses Platform Rate Limits.

Business Discovery and Hashtag Search API are subject to Platform Rate Limits.

Messaging Rate Limits

Calls to the Instagram messaging endpoints are counted against the number of calls your app can make per Instagram professional account and the API used.

Conversations API

Your app can make 2 calls per second per Instagram professional account.

Private Replies API

Your app can make 100 calls per second per Instagram professional account for private replies to Instagram Live comments
Your app can make 750 calls per hour per Instagram professional account for private replies to comments on Instagram posts and reels

Send API

Your app can make 100 calls per second per Instagram professional account for messages that contain text, links, reactions, and stickers
Your app can make 10 calls per second per Instagram professional account for messages that contain audio or video content

LeadGen

Le richieste effettuate dalla tua app all'API LeadGen vengono considerate nel conteggio delle chiamate dell'app. Il conteggio delle chiamate di un'app è il numero di chiamate che può effettuare durante un periodo continuo di 24 ore e viene calcolato come segue:

Calls within 24 hours = 4800 * Leads Generated

Il numero di contatti generati (Leads Generated) corrisponde al numero di contatti generati per Pagina per questo account pubblicitario negli ultimi 90 giorni.

Piattaforma Messenger

Il rate limiting per la Piattaforma Messenger dipende dall'API usata e, in alcuni casi, dal contenuto del messaggio.

API Messenger

Le richieste fatte dalla tua app vengono conteggiate nel numero di chiamate che l'app può effettuare in un periodo continuo di 24 ore, calcolato nel modo seguente:



Calls within 24 hours = 200 * Number of Engaged Users

Il Number of Engaged Users (Numero di utenti con interazioni) è il numero di persone a cui l'azienda può inviare messaggi tramite Messenger.

API Messenger per Instagram

Le richieste fatte dalla tua app vengono conteggiate nel numero di chiamate che l'app può effettuare per account Instagram per professionisti e per l'API usata.

API Conversations

L'app può effettuare 2 chiamate al secondo per account Instagram per professionisti.

API Send

L'app può effettuare 100 chiamate al secondo per account Instagram per professionisti per messaggi che contengono testo, link, reazioni e adesivi.
L'app può effettuare 10 chiamate al secondo per account Instagram per professionisti per messaggi che contengono contenuti audio o video.

API Private Replies

L'app può effettuare 100 chiamate al secondo per account Instagram per professionisti per risposte private a commenti Instagram Live.
L'app può effettuare 750 chiamate all'ora per account Instagram per professionisti per risposte private a commenti su post e reel di Instagram.

Pagine

I rate limiting della Pagina possono utilizzare la logica di rate limiting della piattaforma o BUC a seconda del tipo di token utilizzato. Qualsiasi chiamata API Pages effettuata mediante un token d'accesso della Pagina o un token d'accesso dell'utente di sistema utilizza il calcolo del rate limiting riportato di seguito. Tutte le chiamate effettuate con il token d'accesso dell'app o un token d'accesso dell'utente sono soggette ai rate limiting dell'app o dell'utente.

Le richieste effettuate dalla tua app all'API Pages utilizzando un token d'accesso della Pagina o un token d'accesso dell'utente di sistema vengono considerate nel conteggio delle chiamate dell'app. Il conteggio delle chiamate di un'app è il numero di chiamate che può effettuare durante un periodo continuo di 24 ore e viene calcolato come segue:

Calls within 24 hours = 4800 * Number of Engaged Users

Con numero di utenti con interazioni (Number of Engaged Users) si indica il numero di utenti che hanno interagito con la tua Pagina in un periodo di 24 ore.

Le richieste effettuate dalla tua app all'API Pages utilizzando un token d'accesso dell'utente o un token d'accesso dell'app seguono la logica di rate limiting della piattaforma.

Per evitare problemi di rate limiting quando si utilizza la funzione di Accesso ai contenuti pubblici della Pagina, si consiglia di utilizzare un token d'accesso dell'utente di sistema.

Gestione dell'effetto Commerce di Spark AR

Le richieste effettuate dalla tua app a qualsiasi endpoint Commerce contribuiscono al conteggio delle chiamate dell'app. Il conteggio delle chiamate di un'app è il numero di chiamate che può effettuare durante un periodo continuo di un'ora e viene calcolato come segue:

Calls within one hour = 200 + 40 * Number of Catalogs

Il numero di cataloghi (Number of Catalogs) rappresenta il numero totale di cataloghi in tutti gli account per le vendite gestiti dalla tua app.

Thread

Calls to the Threads API are counted against the calling app's call count. An app's call count is unique for each app and app user pair and is the number of calls the app has made in a rolling 24-hour window. It is calculated as follows:

Calls within 24 hours = 4800 * Number of Impressions

The Number of Impressions is the number of times any content from the app user's Threads account has entered a person's screen within the last 24 hours. Rate limiting may also be subject to total CPU time per day:

720000 * number_of_impressions for total_cputime 

      2880000 * Number of Impressions for total_time

Note: The minimum value for impressions is 10 (so if the impressions is less than 10 we default to 10).

API WhatsApp Business Management

Le richieste effettuate dalla tua app all'API WhatsApp Business Management vengono considerate ai fini del numero di chiamate della tua app. Il numero delle chiamate di un'app corrisponde al numero di chiamate che l'app può effettuare durante un periodo continuo di un'ora. Per l'API WhatsApp Business Management seguente, per impostazione predefinita la tua app può effettuare 200 chiamate all'ora, per app e per singolo account WhatsApp Business (WABA). Per gli account WhatsApp Business attivi con almeno un numero di telefono registrato, la tua app può effettuare 5000 chiamate all'ora, per app, per account WhatsApp Business attivo.

Tipo di chiamata	Endpoint
`GET`	`/{whatsapp-business-account-id}`
`GET`, `POST` e `DELETE`	`/{whatsapp-business-account-id}/assigned_users`
`GET`	`/{whatsapp-business-account-id}/phone_numbers`
`GET`, `POST` e `DELETE`	`/{whatsapp-business-account-id}/message_templates`
`GET`, `POST` e `DELETE`	`/{whatsapp-business-account-id}/subscribed_apps`
`GET`	`/{whatsapp-business-account-to-number-current-status-id}`

Per le seguenti API Credit Line, la tua app può effettuare 5000 chiamate all'ora per app.

Tipo di chiamata	Endpoint
`GET`	`/{business-id}/extendedcredits`
`POST`	`/{extended-credit-id}/whatsapp_credit_sharing_and_attach`
`GET` e `DELETE`	`/{allocation-config-id}`
`GET`	`/{extended-credit-id}/owning_credit_allocation_configs`

Per evitare di raggiungere i rate limiting, è consigliabile usare i webhook per tenere traccia degli aggiornamenti di stato per modelli di messaggi, numeri di telefono e account WhatsApp Business.

Per maggiori informazioni su come ottenere l'utilizzo attuale dei rate, consulta Intestazioni.

Intestazioni

Tutte le risposte API fatte dalla tua app soggette a rate limiting utilizzando la logica BUC includono un'intestazione HTTP X-Business-Use-Case-Usage (per chiamate API Ads versione 3.3 e precedenti) con una stringa in formato JSON che descrive l'utilizzo del rate limiting dell'app corrente. Questa intestazione può restituire fino a 32 oggetti in una chiamata.

Contenuto dell'intestazione X-Business-Use-Case Usage

Codice di errore	Descrizione del valore
`business-id`	L'ID dell'azienda associata al token che effettua le chiamate API.
`call_count`	Un numero intero che esprime la percentuale di chiamate consentite effettuate dalla tua app nell'arco di un periodo continuo di un'ora.
`estimated_time_to_regain_access`	Tempo, in minuti, fino a quando le chiamate non saranno più in throttling.
`total_cputime`	Un numero intero che esprime la percentuale di tempo della CPU assegnato per l'elaborazione delle query.
`total_time`	Un numero intero che esprime la percentuale del tempo totale assegnato per l'elaborazione delle query.
`type`	Tipo di rate limiting applicato. Il valore può essere uno dei seguenti: `ads_insights`, `ads_management`, `custom_audience`, `instagram`, `leadgen`, `messenger` o `pages`.
`ads_api_access_tier`	Solo per i tipi `ads_insights` e `ads_management`. I livelli consentono alla tua app di accedere all'API Marketing. Per impostazione predefinita, le app sono nel livello `development_access`. `Standard_access` consente un rate limiting inferiore. Per ottenere un rate limiting più alto e arrivare al livello standard, puoi richiedere l'"accesso avanzato" alla funzione Accesso standard a Gestione inserzioni.

Tempo di esecuzione totale

La quantità di tempo della CPU necessario per l'elaborazione della richiesta. Quando total_cputime raggiunge 100, le chiamate potrebbero essere sottoposte a throttling.

Tempo totale

Il tempo impiegato per l'elaborazione delle richieste. Quando total_time raggiunge 100, le chiamate potrebbero essere sottoposte a throttling.

Livello di accesso all'API Ads

Solo per i tipi ads_insights e ads_management. I livelli consentono alla tua app di accedere all'API Marketing. Per impostazione predefinita, le app sono nel livello development_access. Standard_access consente un rate limiting inferiore. Per ottenere un rate limiting più alto e arrivare al livello standard, puoi richiedere l'"accesso avanzato" alla funzione Accesso standard a Gestione inserzioni.

Valore dell'intestazione X-Business-Use-Case Usage di esempio

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
        }
    ],
...
}

Codici di errore

Quando l'app raggiunge il rate limiting del caso d'uso aziendale, le successive richieste effettuate dall'app non andranno a buon fine e l'API risponderà con un codice di errore.

Codice di errore	Tipo di rate limiting BUC
`error code 80000, error subcode 2446079`	Insights sulle inserzioni
`error code 80004, error subcode 2446079`	Gestione delle inserzioni
`error code 80003, error subcode 2446079`	Pubblico personalizzato
`error code 80002`	Instagram
`error code 80005`	LeadGen
`error code 80006`	Messenger
`error code 32`	Chiamate alla Pagina effettuate con un token d'accesso dell'utente
`error code 80001`	Chiamate alla Pagina effettuate con un token d'accesso della Pagina o dell'utente di sistema
`error code 17, error subcode 2446079`	API Ads versione 3.3 e precedenti, ad eccezione di insight sulle inserzioni
`error code 80008`	API WhatsApp Business Management
`error code 80014`	Batch catalogo
`error code 80009`	Gestione del catalogo

Esempio di messaggio codice di errore

{   
"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"   
    }
}

Best practice

Quando il limite è stato raggiunto, non effettuare più chiamate API. Continuando a effettuare chiamate continuerai ad aumentare il numero delle chiamate, aumentando il tempo necessario prima che le chiamate tornino a essere eseguite correttamente.
Controlla l'intestazione HTTP X-Business-Use-Case-Usage per vedere quanto è vicino il tuo account pubblicitario al limite e quando puoi riprendere a effettuare chiamate.
Verifica il codice di errore e l'endpoint dell'API per confermare il tipo di throttling.
Passa a un altro account pubblicitario e torna a questo account in un momento successivo.
È consigliabile creare una nuova inserzione, anziché modificare quelle esistenti.
Distribuisci equamente le query tra due intervalli di tempo, per evitare l'invio di picchi di traffico.
Usa i filtri per limitare le dimensioni delle risposte dei dati ed evita chiamate che richiedono dati sovrapposti.

FAQ

Cosa viene considerata una chiamata API?

Il rate limiting prende in considerazione tutte le chiamate, non solo le singole richieste API. Ad esempio, puoi effettuare una singola richiesta API specificando più ID, ma ogni ID conta come una chiamata API.

La seguente tabella illustra questo concetto.

Richiesta/e di esempio Numero di chiamate API

Richiesta/e di esempio	Numero di chiamate API
`GET https://graph.facebook.com/photos?ids=4` `GET https://graph.facebook.com/photos?ids=5` `GET https://graph.facebook.com/photos?ids=6`	3
`GET https://graph.facebook.com/photos?ids=4,5,6`	3

GET https://graph.facebook.com/photos?ids=4

GET https://graph.facebook.com/photos?ids=5

GET https://graph.facebook.com/photos?ids=6

GET https://graph.facebook.com/photos?ids=4,5,6

È consigliabile specificare più ID in una richiesta API quando possibile, poiché ciò migliora le prestazioni delle risposte.

Sto creando un servizio di estrazione, devo preoccuparmi di qualcosa in particolare?

Se stai creando un servizio per estrarre dati, consulta le nostre condizioni per l'estrazione.