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

# Requisições e limites

> Paginação, limites de uso, erros e operações bloqueadas.

## Paginação

Endpoints que retornam listas, como templates, números e usuários bloqueados, devolvem um objeto `paging`:

```json theme={null}
"paging": {
  "cursors": { "before": "QVFIU...", "after": "QVFIU..." },
  "next": "https://graph.facebook.com/v25.0/{WABA_ID}/message_templates?limit=25&after=QVFIU..."
}
```

> [!WARNING]
>
> **Não chame a URL de `paging.next` diretamente.** Ela aponta para a Meta e não funciona sem o token da Meta.

Para buscar a próxima página, repita a mesma chamada na URL da Datafy e acrescente o parâmetro `after` com o valor de `paging.cursors.after`:

```bash theme={null}
curl "https://cloud.datafyapi.com.br/v1/{WABA_ID}/message_templates?limit=25&after=QVFIU..." \
  -H 'Authorization: Bearer sk_live_xxx'
```

Quando não houver mais páginas, a resposta vem sem `paging.next`.

## Limites de requisição

Os limites são contados **por token**, em janelas de 1 minuto. Os endpoints de [Administração](https://developers.datafyapi.com.br/api-reference/administracao/introducao.md) são contados à parte, pelo token de conta:

| Categoria | Rotas | Limite |
| - | - | - |
| Envio de mensagens | `POST /v1/{phone_number_id}/messages` | 4.800 req/min |
| Download de mídia recebida | `GET /media/...` | 6.000 req/min |
| Upload de mídia | `POST /v1/{phone_number_id}/media` | 60 req/min |
| Consultas | Demais endpoints do WhatsApp | 60 req/min |
| Administração de canais | `/channels` | 120 req/min |

Quando o limite é excedido, a API retorna **`429 Too Many Requests`**, com uma mensagem indicando quantos segundos aguardar:

```json theme={null}
{
  "statusCode": 429,
  "message": "Rate limit excedido (60 req/min). Tente novamente em 12s."
}
```

> [!TIP]
>
> Evite consultar o mesmo recurso em loop, como o status do número ou a lista de templates. Para acompanhar mudanças, use os [webhooks](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/receber-eventos.md).

## Erros da Datafy

Antes de repassar a requisição para a Meta, a Datafy valida o token, a assinatura, as rotas bloqueadas e o limite de uso. Nesses casos, a resposta tem os campos `statusCode` e `message`:

```json theme={null}
{
  "statusCode": 401,
  "message": "Token inválido ou não encontrado."
}
```

| Código | Quando acontece |
| - | - |
| `401 Unauthorized` | O header `Authorization` não foi enviado, ou o token é inválido. |
| `402 Payment Required` | O token existe, mas a assinatura da Datafy está inativa. Ative a assinatura no painel. |
| `403 Forbidden` | A operação é bloqueada por segurança, o ID do caminho não pertence ao token, ou um token de Instagram foi usado numa rota de WhatsApp. |
| `409 Conflict` | O canal está pausado e não envia nem recebe mensagens. Libere-o em [Retomar canal](https://developers.datafyapi.com.br/api-reference/administracao/retomar-canal.md). |
| `429 Too Many Requests` | O limite de requisições foi excedido. A mensagem informa quantos segundos aguardar. |

## Erros da Meta

Quando a requisição chega à Meta e ela recusa, a Datafy **repassa a resposta da Meta sem alteração**, com o mesmo status HTTP:

```json theme={null}
{
  "error": {
    "message": "(#131030) Recipient phone number not in allowed list",
    "type": "OAuthException",
    "code": 131030,
    "fbtrace_id": "AbCdEfGhIjK"
  }
}
```

Consulte o significado de cada `code` nos [códigos de erro da Meta](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).

> [!NOTE]
>
> Um envio aceito com **HTTP 200** ainda pode falhar depois, por exemplo, fora da janela de 24 horas. Nesse caso, a falha chega pelo webhook de status.

## Rotas bloqueadas

Algumas operações alteram configurações que a Datafy gerencia para manter seu número funcionando, como o destino dos webhooks. Por segurança, elas retornam **`403 Forbidden`**:

* Caminhos que contêm `subscribed_apps` ou `deregister`.
* `POST` em um ID com os campos `webhook_configuration` ou `pin`, no corpo ou na URL. Eles alteram o destino dos webhooks e o PIN do número.
* `DELETE` direto no ID do número ou da conta do WhatsApp Business.
* Chamadas de número ou de conta com um ID diferente do que está ligado ao token, como `POST /v1/{outro_phone_number_id}/messages`.

```json theme={null}
{
  "statusCode": 403,
  "message": "Operação não permitida via proxy"
}
```

Todos os outros endpoints da Meta Cloud API funcionam normalmente. Veja [Outros endpoints da Meta](https://developers.datafyapi.com.br/api-reference/whatsapp/proxy/outros-endpoints.md).


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