Bucket de Vendas Pendentes
Perfil: Produtor
Área: API de Pagamentos
Para que serve o Bucket de Vendas Pendentes?
Seu objetivo é proteger a operação contra a criação excessiva de vendas em um curto período de tempo, reduzindo riscos operacionais e evitando comportamentos que possam indicar falhas de integração ou geração indevida de cobranças.
Quando o limite configurado é atingido, novas tentativas de criar vendas poderão ser temporariamente bloqueadas até que parte das transações pendentes seja liberada.
Quando esse bloqueio acontece?
Ao tentar criar uma nova venda, a API poderá retornar a seguinte resposta:
{
"success": false,
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "Sua conta atingiu o limite de vendas pendentes para este metodo de pagamento. Aguarde a liberacao do limite ou a atualizacao das vendas pendentes."
}
}Esse retorno indica que a conta atingiu o limite temporário de vendas pendentes para aquele método de pagamento.
Não significa que exista um problema com suas credenciais, API Key ou integração.
Por que esse limite existe?
O Bucket de Vendas Pendentes é uma camada adicional de proteção operacional.
Seu funcionamento é semelhante a outros mecanismos de segurança utilizados no mercado financeiro, como o controle de risco aplicado ao Pix (DICT), onde determinadas operações podem ser temporariamente limitadas quando determinados critérios operacionais são atingidos.
Esse controle evita que uma mesma conta acumule um volume elevado de transações aguardando pagamento ou confirmação em um curto intervalo de tempo.
Todas as contas possuem esse limite?
Não.
O Bucket de Vendas Pendentes depende da configuração operacional da conta.
Sua aplicação pode variar conforme fatores como:
Configuração da conta;
Perfil operacional;
Método de pagamento utilizado.
Caso a conta do seu produtor não possua esse controle habilitado, a criação das transações ocorrerá normalmente, sem passar por essa validação.
Como funciona o Bucket?
Cada venda criada com status PENDING consome uma unidade do limite configurado para aquele método de pagamento.
Enquanto essa venda permanecer pendente, ela continuará ocupando essa unidade.
A unidade será liberada automaticamente quando a venda:
for paga;
for cancelada;
for recusada;
for reembolsada.
Além disso, o limite também é renovado automaticamente quando a janela de tempo configurada expira.
Cada método de pagamento possui seu próprio controle independente.
Por exemplo:
PIX;
Cartão de Crédito;
Boleto.
Isso significa que atingir o limite de vendas pendentes em PIX não impede, necessariamente, a criação de vendas em Cartão de Crédito ou Boleto.
Exemplo prático
Imagine uma conta configurada para permitir até 100 vendas Pix pendentes em uma janela de 10 minutos.
Nesse cenário:
As primeiras 100 vendas serão criadas normalmente.
A 101ª venda poderá retornar o erro TOO_MANY_REQUESTS.
Assim que uma das vendas pendentes for paga, cancelada, recusada ou a janela expirar, uma nova venda poderá ser criada.
Como evitar esse bloqueio?
Na maioria dos casos, nenhuma alteração na integração é necessária.
Como o bloqueio é temporário, recomendamos seguir algumas boas práticas para reduzir sua ocorrência:
Evite criar múltiplas cobranças para o mesmo pedido sem necessidade.
Aguarde a atualização do status da venda por meio dos webhooks antes de gerar uma nova cobrança para a mesma intenção de compra.
Utilize o campo identifier para relacionar a venda ao pedido do seu sistema e evitar duplicidades.
Implemente retentativas utilizando espera progressiva (backoff) quando receber o erro TOO_MANY_REQUESTS.
Perguntas frequentes
Preciso gerar novas credenciais da API?
Não.
Esse erro não está relacionado às credenciais da API.
O limite é permanente?
Não.
O bloqueio é temporário e será removido automaticamente conforme as vendas pendentes forem atualizadas ou quando a janela configurada expirar.
Esse limite considera todos os métodos de pagamento juntos?
Não.
Cada método de pagamento possui um bucket independente.
Por exemplo, atingir o limite de vendas pendentes em PIX não significa que o mesmo ocorrerá para Cartão de Crédito ou Boleto.
Posso solicitar alteração desse limite?
Caso sua operação necessite de um volume maior de vendas pendentes simultaneamente, entre em contato com a equipe de suporte para avaliar sua configuração operacional.
Resumo
O Bucket de Vendas Pendentes é um mecanismo de segurança que limita temporariamente a criação de novas vendas quando uma conta mantém muitas transações pendentes simultaneamente.
Esse controle:
é temporário;
depende da configuração da conta;
funciona de forma independente para cada método de pagamento;
é liberado automaticamente conforme as vendas mudam de status ou a janela configurada expira.
Na maioria dos casos, basta aguardar a liberação do limite ou a atualização das vendas pendentes para que novas transações possam ser criadas normalmente.