Limites de taxa da API

O Elido limita a taxa da API por chave, não por espaço de trabalho. Isso significa que cada integração que você constrói pode saturar seu próprio limite sem deixar as outras sem recursos. Este artigo cobre os limites por plano, os cabeçalhos para ler e como recuar de forma limpa.

Os números#

Limites sustentados por chave:

Plano	Por minuto	Pico (Burst)
Free	60	120
Pro	600	1200
Business	6000	12000

Pico (Burst) é o que você pode exceder brevemente em uma janela de 10 segundos. Sustentado é o limite de estado estacionário em que o balde (bucket) é reabastecido.

Não existem limites por endpoint — um GET /v1/links conta o mesmo que um POST /v1/links. As únicas exceções são:

• POST /v1/bulk-import — 5 importações ativas por espaço de trabalho ao mesmo tempo.
• POST /v1/links com um slug personalizado colidindo com um slug existente — estes ainda contam, mas não reembolsam o slot em caso de conflito.
• GET /v1/analytics/timeseries com interval=second — limitado a 60/minuto mesmo no Business, porque a consulta ClickHouse subjacente é mais pesada.

Cabeçalhos de resposta#

Cada resposta da API inclui:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1747386240

X-RateLimit-Reset é um timestamp Unix informando quando o balde é reabastecido totalmente. Use-o para agendar tentativas em vez de atrasos fixos.

Como é o erro 429#

Quando você excede o limite:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "API rate limit exceeded for this key",
  "retry_after_seconds": 12
}

Retry-After está em segundos. Espere esse tempo e tente novamente. Os SDKs fazem isso automaticamente com jitter; se você estiver escrevendo um cliente HTTP puro, faça o mesmo.

Estratégia de recuo (Backoff)#

Se você estiver sobrecarregando a API (um trabalho em massa pontual, um preenchimento retroativo), ajuste o ritmo do seu cliente no limite sustentado em vez do pico. Um loop ingênuo atinge o limite de pico, para por 50 segundos, atinge o pico novamente — resultando em uma média pior do que apenas manter o ritmo.

Pseudocódigo:

const limit = 600; // per minute
const delayMs = (60 * 1000) / limit; // 100ms between requests

for (const item of items) {
  await fetch(...);
  await sleep(delayMs);
}

Este padrão usa 100% do limite com zero erros 429.

Concorrência#

Solicitações concorrentes compartilham o balde. Se você disparar 100 solicitações paralelas de um pool de trabalhadores no plano Pro (600/min), as primeiras 100 terão sucesso instantaneamente; o balde então será reabastecido a 10/seg. Seu pool de trabalhadores deve visar uma taxa sustentada, não uma profundidade de fila.

Por chave vs por IP#

O balde é por chave, não por IP. Se você estiver usando a mesma chave em 10 máquinas, as 10 máquinas compartilham o limite. Emita uma chave por máquina se precisar de 10× mais margem.

A camada de IP tem um limite separado e muito generoso (10.000/min/IP) destinado apenas a parar clientes fora de controle. Você nunca o atingirá no uso normal; se o fizer, a resposta será 429 com o corpo "error": "ip_rate_limited".

Chaves de idempotência não burlam os limites#

Enviar a mesma Idempotency-Key repetidamente ainda conta cada solicitação contra o seu balde — podemos retornar a resposta em cache sem realizar o trabalho subjacente, mas a contagem é incrementada. Não faça loops em chaves de idempotência como uma estratégia de nova tentativa.

Aumentando os limites#

Se o seu caso de uso realmente precisar de mais de 6000/min sustentados, envie um e-mail para support@elido.app com:

• Seu ID do espaço de trabalho.
• O nome da integração.
• Taxa de solicitação sustentada e de pico esperada.
• Quais endpoints (para que possamos planejar a capacidade para os mais pesados).

Concedemos aumentos de limite por chave para clientes enterprise sob contrato, geralmente em um dia útil.

Solução de problemas#

De repente, recebendo erros 429 em uma chave que costumava funcionar. Ou seu código começou a entrar em loop (most comum), ou outra pessoa no espaço de trabalho começou a usar a mesma chave. Verifique a aba Usage da chave de API no painel para um gráfico por minuto.

Erros 429 na primeira solicitação do dia. Os baldes do nível gratuito resetam em uma janela deslizante, não à meia-noite UTC. Se você testou o limite ontem às 23:59 e ele ainda não foi totalmente reabastecido às 00:01, o primeiro pico ainda estará limitado. Aguarde 60 segundos.

X-RateLimit-Remaining está negativo. Ultrapassagem do pico. O número informa quão profundamente no negativo você está; multiplique por 60/limit para obter os segundos até voltar a zero.