> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Documentação das APIs da DeliveryVip, em português. Regras que mais quebram integrações: (1) Merchant API: faça polling em GET /merchant/v3/events:polling no máximo a cada 30 s por token; confirme todo evento recebido com POST /merchant/v3/events/acknowledgment e corpo [{"id": "<eventId>"}] (o campo lido é id, não eventId), inclusive eventos repetidos ou que o sistema não trata; deduplique por eventId; o evento é só um aviso, busque o pedido na orderURL. (2) Tokens client_credentials valem 24 h e não têm refresh_token: peça outro ao receber 401. (3) Webhooks: valide a assinatura HMAC sobre o corpo bruto e responda 2xx rápido; o polling é a reconciliação. (4) Open Delivery: host od.deliveryvip.com.br, um client_secret por loja, datas em UTC. (5) Fidelidade: o operador implementa 5 rotas assinadas com HMAC e chama o config push; o estorno precisa ser idempotente. (6) Partner API: scope dv.partner. Não invente endpoints: use a referência gerada das specs OpenAPI.

# Rate limiting

> O limite de requisições das APIs da DeliveryVip e como a sua integração deve reagir ao 429.

As APIs da DeliveryVip limitam o volume de requisições para manter a plataforma estável para todas as lojas. Acima do limite, a API responde `429 Too Many Requests` em vez de processar a chamada.

## Limites

| Limite | Valor |
| - | - |
| Requisições por janela | **150** |
| Janela de tempo | **10 segundos** |

Além do limite geral, o polling de eventos tem uma cadência própria: **uma chamada a cada 30 segundos**, exceto para drenar uma fila acumulada. Veja [Consultar novos pedidos](/docs/guides/merchant/order/fluxo-de-integracao/consultar-novos-pedidos.md).

## Ao receber 429

**1. Pare de enviar**

Não repita a chamada imediatamente: cada tentativa dentro da janela conta para o limite.

**2. Espere**

Se a resposta trouxer o header `Retry-After`, espere o tempo indicado. Sem ele, espere ao menos a janela de 10 segundos.

**3. Repita com backoff**

Tente de novo dobrando a espera a cada `429` seguido (10 s, 20 s, 40 s...), com um teto.

> [!WARNING]
>
> Trate o `429` **pelo status HTTP**. O corpo pode não seguir o [formato padrão de erros](/docs/inicio/conceitos/erros.md) e pode nem ser JSON.

```js Node.js theme={null}
async function fetchWithRetry(url, options, attempt = 0) {
  const response = await fetch(url, options)
  if (response.status !== 429 || attempt >= 5) return response

  const retryAfter = Number(response.headers.get('retry-after'))
  const wait = (retryAfter > 0 ? retryAfter : 10 * 2 ** attempt) * 1000
  await new Promise((resolve) => setTimeout(resolve, wait))
  return fetchWithRetry(url, options, attempt + 1)
}
```

```python Python theme={null}
import time
import requests

def request_with_retry(method, url, attempt=0, **kwargs):
    response = requests.request(method, url, **kwargs)
    if response.status_code != 429 or attempt >= 5:
        return response

    retry_after = response.headers.get("Retry-After", "")
    wait = int(retry_after) if retry_after.isdigit() else 10 * 2**attempt
    time.sleep(wait)
    return request_with_retry(method, url, attempt + 1, **kwargs)
```

## Boas práticas

> [!TIP]
>
> **Reaproveite o token.** Ele vale 24 horas. Pedir um token por chamada dobra o número de requisições sem ganho nenhum.

> [!TIP]
>
> **Prefira webhook a polling agressivo.** O [webhook](/docs/guides/merchant/webhooks.md) entrega cada evento na hora, sem consumir o seu limite.

> [!TIP]
>
> **Use cache para o que muda pouco.** Catálogo, dados da loja e horários de funcionamento não precisam ser consultados a cada pedido.

> [!TIP]
>
> **Espalhe as rotinas em lote.** Sincronizações de muitas lojas devem ser distribuídas no tempo, não disparadas todas no mesmo segundo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.