Limites e Boas Práticas

Rate Limiting (Limite de Taxa)

Limites Atuais

100 requisições por minuto por token de API

O contador é resetado a cada 60 segundos (janela deslizante)

Rate limiting aplicado globalmente para todos os endpoints

Resposta ao Exceder o Limite

Quando você excede os limites, receberá:

Boas Práticas para Rate Limiting

Implemente retry com backoff exponencial

Aguarde o tempo indicado no header Retry-After

Use delay crescente entre tentativas

Distribua requisições ao longo do tempo

Evite bursts (rajadas) de requisições

Use filas para operações em lote

Use cache para dados que não mudam frequentemente

A API implementa cache de 30 minutos para consultas

Evite requisições redundantes

Agrupe múltiplas operações quando possível

Use endpoints que suportam operações em lote (ex: /grouped)

Combine filtros para reduzir número de chamadas

Paginação

Parâmetros

Parâmetro	Descrição	Valor Mínimo	Valor Máximo	Valor Padrão
`limit`	Quantidade de registros por página na requisição	1	5000	500
`page`	Número da página de resultados	1	—	1

Como Usar

Ajuste Automático

⚠️ Valores inválidos ou fora dos limites serão automaticamente ajustados:

Valores abaixo do mínimo → ajustados para o mínimo

Valores acima do máximo → ajustados para o máximo

Valores não numéricos → usam valor padrão

Valores decimais → arredondados para baixo (floor)

Exemplos de ajuste:

limit=0 → ajustado para 1

limit=6000 → ajustado para 5000

limit=abc → usa padrão 500

page=0 → ajustado para 1

page=2.7 → ajustado para 2

Exemplo de Resposta Paginada

{
  "data": [...],
  "pagination": {
    "currentPage": 2,
    "totalPages": 15,
    "totalRecords": 1500,
    "limit": 100,
    "hasNextPage": true,
    "hasPreviousPage": true
  }
}

Cache

Configuração de Cache

A API utiliza cache automático para otimizar performance:

Duração do cache: 30 minutos (1800 segundos)

Tipo de cache:

Redis (se configurado via REDIS_HOST)

Database cache (fallback se Redis não disponível)

Estratégias de Cache

Cache de consultas

Queries complexas são cacheadas automaticamente

Cache invalida após 30 minutos ou quando dados são atualizados

Cache no cliente

Implemente cache local para dados estáticos

Respeite TTL (Time To Live) apropriado

Invalide cache quando necessário

Boas Práticas Gerais

1. Tratamento de Erros

Sempre trate possíveis erros da API:

2. Implementação de Retry com Backoff Exponencial

3. Use Paginação Eficientemente

Não busque todos os dados de uma vez

Use limit adequado ao seu caso de uso (recomendado: 500-1000)

Evite limit muito alto que pode causar timeout

Implemente paginação progressiva (lazy loading)

4. Monitoramento

Registre (log) erros e respostas inesperadas

Monitore tempo de resposta

Configure alertas para respostas lentas (> 5s)

Identifique endpoints com performance degradada

Acompanhe uso de quota de requisições

Monitore X-RateLimit-Remaining em cada resposta

Configure alertas quando próximo do limite (ex: < 20 requisições)

5. Otimização de Requisições

Filtros eficientes: Use date ranges e outros filtros para reduzir dados

Requisições paralelas: Limite concorrência para não exceder rate limit

6. Versionamento

Sempre especifique a versão da API

Todos os endpoints começam com /v1/

Monitore comunicados sobre descontinuação de versões

Planeje migração com antecedência

7. Timeouts

Configure timeouts adequados em suas requisições:

Recomendações de timeout:

Requisições GET simples: 10-15 segundos

Requisições com paginação grande: 30-60 segundos

Operações em lote: 60-120 segundos

Checklist de Integração

Antes de colocar em produção, certifique-se de:

Token de API gerado e armazenado com segurança

workspaceId configurado corretamente

Tratamento de erros implementado (incluindo 429)

Rate limiting considerado na arquitetura

Paginação implementada para grandes volumes

Retry com backoff exponencial configurado

Logs e monitoramento configurados

Timeouts configurados adequadamente

Cache implementado quando apropriado

Testes realizados em ambiente de desenvolvimento

Monitoramento de X-RateLimit-Remaining implementado

Troubleshooting

Problemas Comuns

Erros 429 frequentes:

Reduza frequência de requisições

Implemente cache mais agressivo

Use endpoints batch quando disponível

Contate suporte para limites customizados (plano enterprise)

Timeout em requisições grandes:

Reduza o limit da paginação

Use filtros mais específicos (date ranges menores)

Implemente requisições incrementais

Dados inconsistentes:

Verifique se está respeitando cache (aguarde 30 minutos após atualizações)

Use timestamps para sincronização

Considere webhooks se disponível para atualizações em tempo real

Suporte

Para questões sobre limites e boas práticas:

Revise padrões de uso no V4 Marketing

Contate suporte para ajustes de rate limit

Solicite monitoramento customizado para necessidades específicas

Rate Limiting (Limite de Taxa)#

Limites Atuais#

Resposta ao Exceder o Limite#

Boas Práticas para Rate Limiting#

Paginação#

Parâmetros#

Como Usar#

Ajuste Automático#

Exemplo de Resposta Paginada#

Cache#

Configuração de Cache#

Estratégias de Cache#

Boas Práticas Gerais#

1. Tratamento de Erros#

2. Implementação de Retry com Backoff Exponencial#

3. Use Paginação Eficientemente#

4. Monitoramento#

5. Otimização de Requisições#

6. Versionamento#

7. Timeouts#

Checklist de Integração#

Troubleshooting#

Problemas Comuns#

Suporte#