Toda integração saudável faz pausas. O GS Engage limita quantas chamadas você pode fazer por minuto para proteger a estabilidade da plataforma para todo mundo — inclusive para você. Esse teto é o que chamamos de rate limit (limite de requisições por período).

A boa notícia: respeitar o limite é simples. Se você seguir as práticas desta página, sua integração quase nunca vai esbarrar nele — e, quando esbarrar, vai se recuperar sozinha.

A janela é fixa de 60 segundos. A cada novo minuto, a contagem zera.

Na prática, isso é bastante folga para o dia a dia. Listar cadências, buscar leads e acompanhar prospecções cabe com sobra nas 200 leituras por minuto. As 100 escritas por minuto cobrem criação de leads em lote, notas e finalização de prospecções sem apertar.

Se você ultrapassar o teto dentro da janela de 60 segundos, a próxima chamada não é atendida: a API responde com o status HTTP 429 (Too Many Requests, ou "requisições demais").

Junto com o 429 vem o header Retry-After, que diz em quantos segundos você pode tentar de novo. Ele é a informação mais importante da resposta — é a própria API te dizendo o tempo exato de espera.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 12

Essa resposta significa, em português: "você atingiu o limite; espere 12 segundos e siga em frente". Não é um erro da sua chave nem dos seus dados — é só um pedido de pausa.

Toda resposta traz headers que mostram sua situação atual em relação ao limite. Vale a pena lê-los para se antecipar, sem precisar esperar o 429 chegar.

Uma leitura útil: se o X-RateLimit-Remaining está caindo rápido e chegando perto de 0, é hora de reduzir o ritmo — não de acelerar.

Backoff é a técnica de aumentar a espera a cada nova tentativa, em vez de insistir no mesmo intervalo. Backoff exponencial dobra o tempo a cada tentativa (1s, 2s, 4s, 8s...), dando à API espaço para respirar.

A regra de ouro é simples: se a resposta trouxer Retry-After, respeite esse valor. Ele é preciso. Use o backoff exponencial apenas como plano B, quando o header não estiver disponível.

graph TD
A["Faz a requisição"] --> B{"Resposta 429?"}
B -->|Não| C["Segue o fluxo normal"]
B -->|Sim| D{"Tem Retry-After?"}
D -->|Sim| E["Espera os segundos indicados"]
D -->|Não| F["Espera com backoff exponencial (1s, 2s, 4s...)"]
E --> G["Tenta de novo"]
F --> G

O gatilho abaixo é comum: você faz uma chamada e, se levar um 429, espera o tempo certo e tenta de novo automaticamente.

async function chamarComRetry(url, options = {}, tentativas = 5) {
  for (let i = 0; i < tentativas; i++) {
    const resp = await fetch(url, options);

    if (resp.status !== 429) {
      return resp; // deu certo (ou é outro erro que você trata separado)
    }

    // Respeita o Retry-After; se não vier, faz backoff exponencial.
    const retryAfter = Number(resp.headers.get("Retry-After"));
    const esperaSegundos = retryAfter || Math.pow(2, i);

    console.log(`Rate limit atingido. Aguardando ${esperaSegundos}s...`);
    await new Promise((r) => setTimeout(r, esperaSegundos * 1000));
  }

  throw new Error("Limite de tentativas esgotado após vários 429.");
}

// Uso: a apiKey vai como query param na URL
const resp = await chamarComRetry(
  "https://api.gsengage.com/api/v1/leads?apiKey=SUA_CHAVE"
);

import time
import requests

def chamar_com_retry(url, tentativas=5, **kwargs):
    for i in range(tentativas):
        resp = requests.get(url, **kwargs)

        if resp.status_code != 429:
            return resp  # deu certo (ou é outro erro que você trata separado)

        # Respeita o Retry-After; se não vier, faz backoff exponencial.
        retry_after = resp.headers.get("Retry-After")
        espera = int(retry_after) if retry_after else 2 ** i

        print(f"Rate limit atingido. Aguardando {espera}s...")
        time.sleep(espera)

    raise RuntimeError("Limite de tentativas esgotado após vários 429.")

# Uso: a apiKey vai como query param na URL
resp = chamar_com_retry(
    "https://api.gsengage.com/api/v1/leads?apiKey=SUA_CHAVE"
)

Quando esse trecho retorna sem erro, significa que a chamada passou dentro do limite e seus dados chegaram — a espera aconteceu de forma transparente, sem você perder a requisição.

Antes de considerar sua integração pronta, passe por esta lista. Ela evita a maioria dos 429 antes que eles aconteçam.