---
title: "Limites de requisição — BeeFood API"
description: "Limites de requisição e proteção contra uso indevido da API BeeFood: consultas repetidas, bloqueios progressivos e Retry-After."
url: "https://developer.beefood.com.br/docs/limites"
group: "Referência"
lang: "pt"
---
# Limites de requisição

Os limites são aplicados por estabelecimento (empresaId da credencial) e por ambiente. Sandbox e produção têm os mesmos limites. Ao exceder, a API responde 429 Too Many Requests com o header Retry-After, em segundos.

## Grupos e limites

| Grupo | Limite | Rotas |
| --- | --- | --- |
| Pesado | 15 / 60s | GET /v1/store/merchants, GET /v1/store/merchants/{merchantId}, GET /v1/orders |
| Relatórios | 15 / 60s | GET /v1/orders/summary, /grouped, /sectors, /products e /options (cota única entre as cinco rotas) |
| Catálogo | 100 / 180s | Cupons, avaliações, formas de pagamento e rotas de delivery e presencial em /v1/store |
| Polling | 15 / 300s | GET /v1/orders/polling |
| Demais | 300 / 180s | Clientes, catálogo (/v1/catalog), GET /v1/orders/{orderId}, criação e edição de pedidos e demais rotas |

As rotas de OAuth (/v1/oauth/token e /v1/oauth/revoke) não entram nos limites. Prefira webhooks a consultas repetidas para reduzir o número de requisições.

No polling, o intervalo recomendado é de 30 segundos. Ao passar da cota, o 429 traz um Retry-After de poucos segundos, sem penalidade: respeite o header e siga.

### Como tratar o 429

- Leia o Retry-After (em segundos) e espere esse tempo antes de tentar de novo.
- Não repita durante o bloqueio: no uso indevido, insistir aumenta a penalidade.
- Use a message para distinguir os casos: a de uso indevido cita "the same query was repeated"; a de cota é apenas "Too Many Requests".

## 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

| Rota | Consulta |
| --- | --- |
| `GET /v1/orders` | Histórico de pedidos |
| `GET /v1/orders/summary` | Resumo de vendas |
| `GET /v1/orders/summary/grouped` | Resumo por dimensão |
| `GET /v1/orders/summary/sectors` | Ranking por setor |
| `GET /v1/orders/summary/products` | Ranking por produto |
| `GET /v1/orders/summary/options` | Ranking por opção |
| `GET /v1/orders/{orderId}` | Detalhe do pedido (contado por pedido) |

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:

| Rotas | Período observado |
| --- | --- |
| `GET /v1/orders/{orderId}` | Na última hora |
| `GET /v1/orders` e os cinco `GET /v1/orders/summary*` | Em cada uma de duas horas seguidas |

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

| Periodicidade da sua rotina | Chamadas por hora | Resultado |
| --- | --- | --- |
| A cada 1 hora | 1 | Liberado |
| A cada 10 minutos | 6 | Liberado |
| A cada 5 minutos | 12 | Liberado |
| A cada 4 minutos | 15 | Liberado |
| A cada 3 minutos | 20 | **Bloqueado** |
| A cada 1 minuto | 60 | **Bloqueado** |

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

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

| Rota | Limite da mesma consulta | Período |
| --- | --- | --- |
| `GET /v1/orders` e os cinco `GET /v1/orders/summary*` | 20 por hora | Duas horas seguidas |
| `GET /v1/orders/{orderId}` | 20 por hora, para o mesmo pedido | Uma hora |
| `GET /v1/orders/polling` | Fora desta regra (cota própria, sem penalidade) | — |

### 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

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

```

```json

{
  "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**.

| Detecção | Duração |
| --- | --- |
| 1ª | 15 minutos |
| 2ª | 30 minutos |
| 3ª | 1 hora |
| 4ª | 2 horas |
| 5ª | 4 horas |
| 6ª | 8 horas |
| 7ª | 16 horas |
| 8ª em diante | 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](/docs/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.