Limites
Dois tipos, com respostas diferentes: quantas requisições você pode fazer, e quanto dinheiro a conta pode movimentar.
Requisições por minuto
| Escopo | Limite | Resposta ao estourar |
|---|---|---|
| Por chave de API (sandbox) | 60/min | 429 RATE_LIMITED |
| Por chave de API (produção) | definido na emissão, até 120/min | 429 RATE_LIMITED |
| Por endereço de origem | 120/min | 429 RATE_LIMITED |
| Tentativas de senha ou de código (no login e na recuperação de senha, por documento e origem) | 5 a cada 15 min | 429 TOO_MANY_ATTEMPTS |
O limite por chave existe porque o console de testes desta documentação é público: um balde por endereço faria um único abusador atrás de NAT derrubar todo mundo que compartilha aquela saída.
Toda resposta 429 traz Retry-After, em segundos. Respeite-o. Um laço apertado de repetição em cima de um limite de taxa só afunda mais o balde.
Limites de valor
São da conta, e não da chave. Consulte os que estão em vigor a qualquer momento — eles mudam por decisão do titular ou por política do banco:
{
"pixDailyCents": 500000,
"pixSingleCents": 200000,
"pixNightCents": 100000,
"pixNightNewPeerCents": 10000,
"tedDailyCents": 2000000,
"billetSingleCents": 1000000,
"billetDailyCents": 3000000,
"cardDailyCents": 300000,
"stepUpThresholdCents": 100000,
"stepUpDailyThresholdCents": 100000,
…
}| Campo | O que limita |
|---|---|
pixDailyCents | Soma dos PIX enviados pela conta no dia (chave, agência e conta, QR Code e devolução), com a virada do dia no fuso da operação. |
pixSingleCents | Valor máximo de uma única transferência. |
pixNightCents | Teto na janela noturna, das 20h às 6h, por operação e pela soma do que a conta já enviou ou reservou por PIX e TED na janela. |
pixNightNewPeerCents | Teto noturno para um destino que a conta não pagou antes do início da janela, por operação e pela soma para esse destino. Veja abaixo. |
tedDailyCents | Soma das TEDs enviadas no dia. |
billetSingleCents, billetDailyCents | Valor por pagamento de boleto ou de conta, e a soma desses pagamentos no dia. |
cardDailyCents | Política de compras com cartão, configurada pelo banco. |
stepUpThresholdCents | A partir daqui a transferência exige X-Step-Up, mesmo com credencial válida. |
stepUpDailyThresholdCents | Soma do dia a partir da qual o envio sem X-Step-Up também o exige, ainda que abaixo de stepUpThresholdCents. |
Estourar um teto de valor responde 422 LIMIT_EXCEEDED, antes de qualquer débito, e a mensagem diz o que falta ou o que resta: a diferença entre “limite excedido” e saber o que fazer a respeito. Passar da soma do step-up não é limite: responde 403 STEP_UP_REQUIRED, e com o código a operação segue.
Por que a janela noturna é diferente
Uma transferência de madrugada, de um aparelho nunca visto, para uma chave nunca usada é um padrão diferente da mesma transferência de dia. O limite noturno para contato novo é o mais baixo de todos por isso, e é o que a Resolução BCB nº 142 endereça.
Um pagamento feito dentro da própria noite não torna o destino conhecido: vale o que a conta pagou antes das 20h. Os tetos noturnos valem também ao liberar uma transação retida — se a liberação passar deles, é recusada e a transação segue retida.
O aparelho que a análise de risco considera é o da sessão: o deviceFingerprint enviado em POST /v1/auth/login. Envie-o sempre que a sua tela abrir sessão em nome de um usuário final. Chamadas por chave de API não têm aparelho, e a análise as trata como de aparelho desconhecido.
Retenção não é limite
Uma transferência dentro de todos os limites ainda pode parar em HELD_FOR_REVIEW se o motor de risco vir um padrão incomum. Não é recusa: o titular decide, e bloquear devolve o dinheiro na hora. Liberar só vale depois de 15 minutos de retenção, e uma retida com riskScore 85 ou mais só o banco libera. Trate esse estado no seu fluxo — ele é o desfecho mais fácil de esquecer, e o mais visível para o cliente final quando esquecido.