Limiti di velocità

La X Ads API è soggetta a limiti di velocità in modo analogo alla REST API v1.1, come documentato qui: REST API Rate Limiting in v1.1. A differenza della REST API v1.1, non esiste un indice programmatico dei limiti per endpoint. I limiti di velocità degli endpoint e le finestre di reset sono comunicati tramite le intestazioni di risposta HTTP. Tutti i limiti di velocità nella X Ads API utilizzano OAuth 1.0a.

Limiti a livello utente e a livello di account pubblicitario

Esistono due tipi di limiti di velocità: a livello di token utente e a livello di account pubblicitario. Un sottoinsieme di endpoint è abilitato per utilizzare il limite di velocità a livello di account pubblicitario. Un token utente è l’OAuth access token che usi per autenticarti e chiamare la X Ads API. Ogni token utente può avere accesso a uno o più account pubblicitari. Gli sviluppatori dovrebbero utilizzare il limite di velocità a livello di account pubblicitario quando è restituito nelle intestazioni di risposta e ricorrere al limite a livello utente solo quando il limite dell’account pubblicitario non è presente. I limiti di velocità a livello utente sono espressi tramite queste intestazioni: x-rate-limit-limit, x-rate-limit-remaining e x-rate-limit-reset. Per gli endpoint con limitazione a livello di account pubblicitario abilitata, i limiti di velocità sono espressi tramite queste intestazioni: x-account-rate-limit-limit, x-account-rate-limit-remaining e x-account-rate-limit-reset. I limiti di velocità a livello di account pubblicitario sono forniti solo per gli endpoint GET per consentire alle applicazioni di sincronizzare i dati delle entità (come gli oggetti campaign o line item) da un singolo token utente che accede a più account pubblicitari. Le azioni di scrittura non sono garantite a utilizzare gli stessi limiti di velocità a livello di account pubblicitario. Per gli endpoint limitati a livello di account pubblicitario, il limite di velocità a livello utente è impostato su un valore elevato che rappresenta una quota globale per l’intera applicazione. Quando disponibile, il limite di velocità a livello di account pubblicitario dovrebbe avere la precedenza nel controllo del volume delle richieste.

Best Practices

Salva nel tuo database un timestamp relativo all’ultima sincronizzazione e, quando possibile, richiedi i dati con l’opzione sort_by=updated_at-desc per poter interrompere il processo di sincronizzazione una volta raggiunti dati più vecchi dell’ultimo timestamp sincronizzato. In questo modo eviterai di sincronizzare nuovamente gli stessi dati.
Richiedi più entità in un’unica richiesta: alcuni endpoint consentono di specificare un elenco di valori separati da virgole per recuperare più dati simili. Ciò può ridurre il numero complessivo di chiamate e quindi sfruttare il rate limit in modo più efficiente.
Richiedi il valore massimo di “count” nelle tue richieste: per alcuni endpoint, come GET accounts/:account_id/targeting_criteria, è fortemente consigliato usare il valore massimo di count per ottenere 1000 oggetti invece del valore predefinito di 200.

Sincronizzazione delle analytics

Consulta la Guida ai limiti di velocità delle analytics per ulteriori informazioni sui limiti di velocità dell’endpoint analytics.

Domande frequenti

È possibile aumentare i limiti di velocità per un determinato account pubblicitario o per la nostra applicazione? In genere non possiamo aumentare i limiti di velocità, che sono configurati per supportare anche gli account pubblicitari di maggiori dimensioni. Come primo passo, applica le Best Practices indicate in questo documento e, se i limiti di velocità continuano a incidere sulla tua capacità di scalare o raggiungere gli obiettivi di business, contatta i tuoi referenti della X Ads API fornendo dettagli completi sul caso d’uso e sulle richieste coinvolte.

Ambiti del rate limit

Ambiti per questo documento

Categoria: tutti gli endpoint appartenenti alla categoria indicata condividono un unico limite allocato per finestra (limite di velocità).
Endpoint: ogni endpoint dispone di un proprio limite allocato, distinto, per finestra.

Tabella dei limiti di velocità della X Ads API