Conceitos básicos

Limites de uso

Cada chave pode fazer 120 requisições por minuto, e toda resposta diz quantas ainda restam.

Limites

Limite	Vale para
120 requisições por minuto	Cada chave de API, em todos os endpoints. O minuto é uma janela fixa que começa no minuto cheio.
10 exportações por hora	Cada conta, em Criar uma exportação. Acima disso, 429 `export_rate_limit_exceeded`.
10 DMs por minuto	Cada conta do X, em Enviar uma mensagem. Acima disso, 429 `dm_rate_limited`.
300 DMs por dia	Cada conta do X, por dia em UTC, ou menos quando o X define uma cota menor. Acima disso, 429 `dm_daily_limit`.
5 tentativas de código por hora	Cada conta, em Definir o código do X Chat. Acima disso, 429 `passcode_rate_limited`.
6 mensagens ao Julien AI por minuto	Cada conta do X, em Enviar uma mensagem e na ferramenta MCP `ask_julien_ai`. Acima disso, 429 `assistant_rate_limited`.
100 mensagens ao Julien AI por dia	Cada conta do X, por dia em UTC. Acima disso, 429 `assistant_daily_limit`.
Uma mensagem ao Julien AI por vez	Cada chat, e 3 chats ao mesmo tempo por conta do X. Acima disso, 409 `assistant_busy`.

Cabeçalhos de limite de uso

Toda resposta traz o estado da janela da chave.

Cabeçalho	Significado
`RateLimit-Limit`	Requisições permitidas em uma janela, `120`.
`RateLimit-Remaining`	Requisições que restam na janela atual.
`RateLimit-Reset`	Segundos até a janela recomeçar.
`Retry-After`	Apenas em um 429, os segundos a esperar antes de tentar de novo.

Cabeçalhos

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 17
Retry-After: 17
Request-Id: req_3Vb8YzC1dF6hJ0sW

Resposta429

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. This key can make 120 requests a minute.",
    "param": null,
    "request_id": "req_3Vb8YzC1dF6hJ0sW",
    "doc_url": "https://gemlead.ai/docs/errors#rate_limit_exceeded"
  }
}

Tratar um 429

Espere Retry-After segundos e envie a mesma requisição de novo.

Distribua os trabalhos grandes ao longo do tempo em vez de enviar tudo em rajadas.
Leia RateLimit-Remaining para desacelerar antes de chegar a zero.
Para puxar muitos leads de uma vez, uma exportação é melhor que centenas de páginas.
Os webhooks levam os eventos até você, então você não gasta requisições fazendo polling atrás de leads novos.

# curl waits for Retry-After, then tries again
curl --retry 5 https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"