Uso indevido

As rotas de clientes, catálogo e restaurante devolvem dados que mudam devagar: um cardápio não se altera a cada minuto, e a base de clientes cresce aos poucos. Reler tudo continuamente é varredura robótica, não sincronização.

Aqui não é medida a repetição da mesma URL. Uma integração que percorre ?page=1, ?page=2, ?page=3… nunca repete URL nenhuma, mesmo rodando sem parar. O que é medido é o volume total da rota, somando todas as páginas, todos os filtros e todos os ids.

Todas as rotas da lista ficam bloqueadas para o estabelecimento, não apenas a consulta que disparou. O bloqueio vale para o empresaId da credencial no ambiente em que ocorreu (produção ou sandbox).

HTTP/1.1 429 Too Many Requests
Retry-After: 900

{
  "message": "Too Many Requests: the same query was repeated too many times; reduce the polling frequency. See https://docs.beefood.app/docs/limites",
  "status": 429
}

O status é o mesmo dos limites por janela. A diferença está na message, que cita the same query was repeated, e no tempo maior em Retry-After.

O primeiro bloqueio dura 15 minutos e dobra a cada nova detecção, até 24 horas.

As chamadas que recebem 429 continuam contando. O degrau só sobe com uma chamada nova feita depois do bloqueio em vigor.

Parando o laço, o bloqueio atual é o último e expira sozinho, sem chamado. Após 24 horas sem reincidência, a contagem volta ao primeiro degrau.

As respostas 429 desta regra também contam na régua diária. Um laço que passe semanas tomando penalidade de 24 h acumula 429 suficiente para desativar a credencial, mesmo com cada penalidade expirando sozinha.

• Pedidos em tempo real: use webhooks. Se não puder recebê-los, use GET /v1/orders/polling a cada 30 segundos, que está fora desta regra.

• Acompanhar um pedido: GET /v1/orders/{orderId} não gera mais penalidade por repetição, mas chamá-lo em laço continua sem produzir informação nova. Use webhooks ou o polling para saber que o pedido mudou.

• Relatórios: consulte em intervalos de 5 minutos ou mais e guarde o resultado em cache. Para dias fechados, consulte uma vez e reaproveite.

• Pedido específico: use GET /v1/orders/{orderId} em vez de listar e filtrar.

• Resposta 429: respeite o Retry-After. Repetir a chamada durante o bloqueio aumenta a penalidade.

• Clientes, catálogo e restaurante: sincronize uma vez e guarde o resultado. Esses dados mudam devagar: uma varredura completa por dia, ou por hora no máximo, cobre qualquer cenário. Não repagine a base inteira em intervalos curtos só para descobrir o que mudou.