API Limits
A Selectwin implementa limites de uso na API para garantir a estabilidade, disponibilidade e desempenho consistente da plataforma para todos os integradores. Este documento detalha os diferentes tipos
Visão Geral
A Selectwin implementa limites de uso na API para garantir a estabilidade, disponibilidade e desempenho consistente da plataforma para todos os integradores. Este documento detalha os diferentes tipos de limitações, como monitorá-las e as melhores práticas para evitar problemas relacionados a esses limites.
Rate Limits
O rate limiting é aplicado a todas as requisições à API Selectwin, limitando o número de chamadas que podem ser feitas em um determinado período. Estes limites protegem a infraestrutura contra sobrecargas, garantem uma distribuição justa de recursos e previnem abusos. A contagem é feita por IP de origem dentro de uma janela de tempo configurável.
Como funciona
O limite é aplicado em dois níveis:
- Um limite padrão, aplicado à maioria dos endpoints.
- Um limite mais estrito para endpoints sensíveis de autenticação (login, MFA, recuperação de senha, signup, verificação de e-mail, registro de passkey, token M2M e step-up).
Os valores exatos podem ser ajustados pela operação e para a sua empresa mediante solicitação. Ao
exceder, a API responde 429 Too Many Requests; o cabeçalho HTTP Retry-After (em segundos) indica
quando tentar novamente.
Limites por Rota (representativo — não normativo)
A tabela a seguir é apenas ilustrativa para dar uma noção de ordem de grandeza; os valores reais seguem o esquema de dois níveis descrito acima e podem diferir. Operações de autenticação recebem o limite mais estrito.
| Grupo | Rota (exemplo) | Método | Limite/min | Bloqueio após excesso |
|---|---|---|---|---|
| Autenticação | /v1/authentication/token | POST | 5 | 15 min |
| Autenticação | /v1/authentication/signup, /recovery/request | POST | 3 | 15 min |
| Autenticação | /v1/authentication/token/mfa, /step-up | POST | 5–10 | 5 min |
| Transações | /v1/transactions (listar/ler) | GET | 60 | — |
| Transações | /v1/transactions (criar) | POST | 30 | 30s |
| Transações | /v1/transactions/{id}/refund · /capture | POST | 10 | 2 min |
| Transações | /v1/transactions/{id}/dispute | POST | 5 | 5 min |
| Clientes / Produtos / Assinaturas | listar/ler | GET | 60 | — |
| Carteiras / Saques / Cartões / Endereços / Cupons / Webhooks | listar/ler | GET | 30 | — |
| Saques | /v1/withdrawals (criar) | POST | 10 | 60s |
| Finance | /v1/finance/balance | GET | 30 | — |
| Recebíveis (analytics) | /v1/receivables/analytics | GET | 15–20 | — |
A tabela acima é representativa; cada rota tem seu próprio alvo. Os limites podem ser ajustados para a sua empresa mediante solicitação (veja FAQ).
Resposta ao Exceder o Limite
Ao ultrapassar um limite, a API responde com HTTP 429 Too Many Requests (envelope de erro padrão,
category: "rate_limit"). Aguarde o tempo indicado no cabeçalho Retry-After (segundos) antes de repetir
a chamada e implemente backoff exponencial. O contador é por IP de origem e reinicia ao fim da janela.
Melhores Práticas
1. Use Webhooks em vez de Polling
O uso de polling (consultas repetidas para verificar mudanças) é desencorajado e pode levar a problemas com rate limits. Em vez disso, utilize webhooks para ser notificado automaticamente sobre mudanças:
2. Priorize Recursos Críticos
Identifique quais operações são críticas para seu negócio e reserve capacidade para elas:
3. Otimize o Tamanho das Requisições
Reduza o tamanho das requisições para melhorar o desempenho e evitar problemas com limites de payload:
- Remova campos desnecessários
- Utilize compressão quando disponível (HTTP gzip)
- Otimize o formato de imagens e arquivos anexados
- Divida grandes volumes de dados em lotes menores
Perguntas Frequentes
Posso solicitar limites personalizados?
Sim, podemos aumentar os limites de uso da API conforme a necessidade da sua empresa. Entre em contato com nosso suporte técnico para discutir suas necessidades específicas e encontrar a melhor solução.
Os limites são os mesmos nos ambientes de sandbox e produção?
Sim, os ambientes de sandbox e produção compartilham os mesmos limites de API para garantir que você possa testar adequadamente a integração com as mesmas condições que encontrará em produção.
Há diferença de limites entre horários de pico e fora de pico?
Não, os limites são aplicados consistentemente independentemente do horário. No entanto, recomendamos agendar operações em lote, como relatórios e sincronizações, para horários de menor movimento (geralmente durante a madrugada).
Como fazer para solicitar o aumento de limite de requisições para minha empresa?
Para solicitar o aumento de limite de requisições, entre em contato com nosso suporte técnico através do e-mail [email protected] ou pelo Painel Administrativo. Nossa equipe avaliará sua solicitação e fornecerá as orientações necessárias.