Limites de requisição

Uso indevido

Além dos limites por janela de tempo, as consultas de pedidos, relatórios e detalhe do pedido têm uma proteção contra a repetição automática da mesma consulta. Ela protege o sistema do restaurante de consultas que não produzem informação nova.

Rotas afetadas

Não entram: GET /v1/orders/polling e as rotas de criação e edição de pedidos.

A regra

A mesma consulta — mesma rota, mesmos filtros — não pode se repetir 20 vezes ou mais por hora.

O período observado depende da rota:

No detalhe, reler o mesmo pedido nesse ritmo interrompe o laço já na primeira hora. No histórico e nos relatórios, um pico isolado não bloqueia: o padrão precisa persistir por duas horas seguidas.

"Mesma consulta" é a URL completa com a querystring. Trocar o período, o groupBy ou a página faz uma consulta diferente.

No detalhe do pedido, a contagem é por pedido: percorrer pedidos diferentes não conta. Nenhum pedido muda a ponto de justificar 20 leituras na mesma hora; para saber de mudanças, use webhook ou polling.

A repetição nesse ritmo é uso indevido, mesmo respeitando os limites por janela.

Onde fica a linha

Na prática, use intervalos de 5 minutos ou mais: nesse ritmo nenhuma das janelas é atingida.

Proteção contra repetição da mesma consulta

A resposta

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.

A penalidade aumenta

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.

Como ajustar a integração

• 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: não reconsulte GET /v1/orders/{orderId} em laço. Use webhooks ou o polling.

• 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.

Perguntas frequentes

Fui bloqueado mas minha rotina é legítima. Verifique o intervalo: a linha fica entre 3 e 4 minutos. Use 5 minutos ou mais; se seu caso não se encaixa, fale com o suporte.

O bloqueio afeta meus outros aplicativos? Sim. A penalidade é do estabelecimento, não da credencial; todas as integrações do restaurante no mesmo ambiente são afetadas.

Paginar conta como repetição? Não, cada página é uma consulta diferente. Reiniciar a varredura a cada poucos minutos, porém, repete a página 1 e pode disparar a regra.

Preciso pedir desbloqueio? Não. Corrigida a frequência, a penalidade expira sozinha.