Limites de uso e boas maneiras

Esta página separa o que a API impõe hoje do que recomendamos que o seu cliente faça. A recomendação serve mesmo quando a API ainda não impõe nada.

Limites conhecidos

Limite	Valor
Validade do token	2 minutos
Validade da chave de API	90 dias por padrão, máximo de 365
Janela por consulta	até 400 dias (180 em `sugestoes-de-desempenho`)
`limit` de `audit/revisions`	1 a 1000, padrão 100

A API não publica hoje um limite numérico de requisições por minuto para as rotas de leitura. Escreva o cliente como se ele existisse: respeite 429 e 503 se aparecerem, e use as práticas abaixo.

Frequência de consulta

Os dados vêm das plataformas de anúncio em coletas periódicas, não em tempo real. Consultar a cada poucos segundos não traz número novo.

Para painéis e rotinas, uma consulta por hora costuma bastar.
Para fechamento diário, consulte uma vez ao dia, depois de a coleta ter passado, e releia a janela de revisão (28 dias). Veja Unidades e tipos.
Use last_observed_at de /accounts para saber se há dado novo antes de repetir uma consulta pesada.

Retry com backoff

Repita apenas o que pode dar certo na segunda vez: falhas de rede, 5xx e, se aparecer, 429 ou 503. Nunca repita 400, 401 com chave inválida ou 403 sem mudar algo.

Padrão recomendado:

Espere 1 segundo, depois 2, 4, 8, até um teto de 30 segundos.
Some um valor aleatório de até 25% a cada espera, para vários clientes não repetirem juntos.
Pare depois de 5 tentativas e registre o trace_id.
Se a resposta trouxer o cabeçalho Retry-After, respeite-o.

Exemplo em Python:

import random
import time

import requests

def get_com_retry(url, headers, tentativas=5):
    espera = 1.0
    for n in range(tentativas):
        try:
            r = requests.get(url, headers=headers, timeout=30)
            if r.status_code < 500 and r.status_code != 429:
                return r
        except requests.RequestException:
            pass
        if n == tentativas - 1:
            break
        time.sleep(min(espera, 30) * (1 + random.random() * 0.25))
        espera *= 2
    raise RuntimeError("API indisponível depois de várias tentativas")

Idempotência de leitura

Toda rota publicada é GET, exceto POST /v1/token. Ler é idempotente: repetir uma leitura não altera nada no servidor, e não existe chave de idempotência a enviar. Repetir POST /v1/token também é seguro, só emite outro token.

Cache

Token. Reaproveite-o até expires_at menos uma folga. Não grave em disco.
Respostas. Dados de períodos fechados mudam pouco, mas mudam (revisões retroativas). Faça cache de períodos antigos por horas, não por semanas, e releia sempre os últimos 28 dias.
Dados quase estáticos. plano/vocabulario é a mesma resposta para todo cliente e não muda com a janela: faça cache longo.
Imagens de criativos. As URLs da rota creatives apontam para objetos endereçados por conteúdo e o endereço muda se a peça mudar. Não guarde a URL; guarde o campaign_id ou o identificador da peça e consulte de novo.
Segurança do cache. Não coloque tokens, chaves nem respostas de um cliente num cache compartilhado com outro cliente.

Boas maneiras

Peça só a janela de que precisa.
Guarde a chave de API em gerenciador de segredos e rotacione antes do vencimento. Crie a nova chave, troque na integração, depois revogue a antiga.
Use uma chave por integração, com o menor escopo de contas possível. Revogar uma não derruba as outras.
Avise o seu time uns 15 dias antes de a chave vencer. Uma chave vencida para a integração.
Registre o trace_id dos erros.
Não envie a chave nem o token em URL, corpo ou log.