Limites de requisições

A Ligga API limita o volume de requisições por chave de API, em três camadas que valem ao mesmo tempo: por segundo, por minuto e por dia. Os tetos vêm do plano da conta, com ajustes por contrato quando existem. Toda resposta carrega os cabeçalhos X-RateLimit-*, e estourar qualquer uma das camadas produz um 429.

As três camadas

Camada	Janela	O que conta	Retry-After
Pico	1 segundo	Todas as requisições, de leitura e de escrita	1
Minuto	60 segundos	Duas contagens separadas: leitura (GET) e escrita (POST, PATCH, DELETE)	60
Dia	24 horas	Todas as requisições, sem separar leitura de escrita	86400

A camada de pico existe para absorver rajadas antes que elas consumam a cota do minuto. As três são avaliadas em ordem, e a primeira que estourar responde 429.

Toda requisição autenticada conta, qualquer que seja o resultado. Uma chamada que termina em 404 ou 422 consome cota igual a uma que termina em 200.

Os limites que valem para você

Peça a GET /v1/me. A resposta traz o plano em vigor e os quatro tetos aplicados à chave que fez a chamada:

curl "$LIGGA_BASE/v1/me" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "plan_code": "pro",
    "rate_limits": {
      "burst_per_second": 20,
      "requests_per_minute_read": 300,
      "requests_per_minute_write": 120,
      "requests_per_day_total": 100000
    }
  },
  "meta": { "request_id": "req_9f2c1a7b4d8e4f0a91c3b5d7e2f40a68" }
}

Os valores por plano hoje são estes:

plan_code	Pico (por segundo)	Leitura (por minuto)	Escrita (por minuto)	Total (por dia)	Chaves simultâneas
free	5	30	10	1.000	1
starter	10	60	30	10.000	3
pro	20	300	120	100.000	10
enterprise	50	1.000	500	1.000.000	99

Nota

Esta tabela é referência, não contrato. Os tetos por plano são ajustáveis sem nova versão da API, e um contrato pode ter valores próprios. O que vale para a sua chave é sempre rate_limits na resposta de GET /v1/me.

Cabeçalhos de resposta

Toda resposta a uma requisição autenticada, com sucesso ou com 429, carrega:

X-RateLimit-Limit: 300
X-RateLimit-Remaining:
X-RateLimit-Reset: 1715990460

Cabeçalho	Descrição
X-RateLimit-Limit	Teto da janela de minuto aplicada à requisição. Em um 429, o teto da camada que estourou
X-RateLimit-Remaining	Quanto resta na janela. Hoje vem vazio nas respostas de sucesso, porque a contagem exata não é exposta, e 0 no 429
X-RateLimit-Reset	Momento em que a janela reinicia, em segundos desde a época Unix

No 429, some-se a eles o Retry-After, em segundos:

Retry-After: 60

Cuidado

Não dimensione o seu tráfego por X-RateLimit-Remaining: enquanto ele vier vazio, não há contagem a ler. Use os tetos de GET /v1/me para calcular o ritmo, e o Retry-After para reagir ao 429.

O corpo do 429

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1715990460

{
  "type": "https://api.ligga.app/errors/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "120 requests per minute reached on plan 'pro'",
  "instance": "/v1/sales",
  "request_id": "req_9f2c1a7b4d8e4f0a91c3b5d7e2f40a68"
}

O detail diz qual camada estourou: per second, per minute ou per day.

Requisições sem chave válida

Requisições que chegam sem Authorization, ou com uma chave que a API não reconhece, são contadas em um limite separado, por endereço IP: 30 por minuto. Elas não consomem a cota de nenhuma chave, e o excesso também responde 429, com Retry-After: 60.

Esse limite existe para conter tentativa de adivinhação de chave. Na prática ele só aparece quando uma integração roda com a variável de ambiente vazia.

Boas práticas

• Trate o 429 com espera crescente entre as tentativas, sempre começando pelo Retry-After.
• Calcule o ritmo pelos tetos de GET /v1/me, e deixe folga: a camada de pico reprova uma rajada bem antes de a cota do minuto acabar.
• Em carga pesada, como uma carga inicial ou uma sincronização noturna, distribua o trabalho ao longo da janela diária em vez de disparar tudo nos primeiros minutos.
• Prefira menos requisições grandes a muitas pequenas: limit=100 e o parâmetro fields reduzem o número de chamadas necessárias para percorrer uma lista.
• Se a sua integração legítima encosta no teto do plano com frequência, fale com o time da Ligga antes de espremer o cliente.

Veja também

• Sua conta (me) — os campos de rate_limits
• Erros — o catálogo completo, incluindo rate-limit-exceeded
• Paginação, filtros e ordenação — como buscar mais dados por chamada
• Idempotência — repetir uma escrita sem duplicar registro