Limites e quotas¶

Para: Dev — Conferido em 2026-10-18.

A API limita a taxa de chamadas em vários baldes (por IP, por chave, por operação, por jogador) e limita o tamanho e o formato de cada campo. Esta página lista todos os baldes, mostra como o token bucket se comporta e reúne os limites de tamanho num só lugar.

O que é¶

Cada balde é um token bucket com duas medidas:

• taxa: quantas fichas voltam por segundo (ou por hora, no caso dos limites por jogador);
• rajada (burst): quantas fichas o balde guarda, ou seja, quantas chamadas você pode fazer de uma vez com o balde cheio.

Cada chamada gasta uma ficha de cada balde que se aplica a ela. Se algum balde está vazio, a resposta é 429 rate_limited com Retry-After (em segundos, arredondado para cima, no mínimo 1) dizendo quando haverá ficha. Não é um "contador por segundo fixo": um balde de 50/s com rajada 100 deixa passar 100 chamadas de uma vez e depois 50 por segundo de forma contínua.

O limitador é compartilhado entre todos os servidores do Dracma, então o limite vale para o conjunto. Se ele próprio estiver indisponível, a resposta é 503 service_unavailable com Retry-After: 1: o Dracma nunca aceita "sem limite" quando não consegue contar.

Os valores abaixo são os mesmos em operações Teste e Real, e iguais para todas as operações. Não há perfil "menor" para Teste.

Quando usar¶

Use a tabela para dimensionar o conector: tamanho de pool de conexões, ritmo de varredura de listagens e fila de saques. Os limites por jogador (10 depósitos e 3 saques por hora) também orientam a tela do seu produto: vale mostrar "tente mais tarde" em vez de deixar o jogador repetir.

Como funciona¶

Baldes de taxa¶

Balde	Taxa	Rajada	Chamadas que gastam a ficha
IP de origem, antes da autenticação	200/s	200	toda chamada /v1
Chave, escrita	50/s	100	POST
Operação, escrita	50/s	100	POST
Chave, leitura	100/s	100	GET e HEAD
Operação, leitura	200/s	200	GET e HEAD
Listagem, por chave	5/s	5	GET /deposits, GET /withdrawals, GET /events e GET /receipts, sem id
Depósitos criados por jogador (player.external_ref)	10/hora	10	POST /deposits
Saques pedidos por jogador (player.external_ref)	3/hora	3	POST /withdrawals
Falhas de assinatura, por IP	20/minuto	20	cada 401 invalid_signature

Uma chamada de escrita gasta uma ficha do balde da chave e uma do balde da operação; uma listagem gasta as fichas de leitura (chave e operação) e a de listagem. Vale o balde mais restritivo.

Consequências práticas:

• Fetch-back não é listagem. GET /deposits/{id} e GET /withdrawals/{id} usam só os baldes de leitura (100/s por chave). Faça o fetch-back por id; use a listagem por external_id apenas para recuperar um POST perdido.
• A listagem é o gargalo. Com 5/s e limit=200, o teto de varredura é de 1.000 itens por segundo. Pagine com pausa de 200 ms (Paginação e filtros).
• GET /reconciliation não está no balde de listagem. Ele usa os baldes de leitura (100/s por chave). O contrato fala em 5 req/s para ele; a API hoje aplica o balde de leitura. Não conte com a folga: um relatório por dia e por moeda não precisa de mais.
• Falhas de assinatura. Com 20 falhas por minuto do mesmo IP, a resposta deixa de ser 401 e vira 429 rate_limited. Um conector com a chave errada, em laço, tranca o próprio IP; corrija a causa em vez de repetir.

Limites por jogador¶

Dois baldes protegem um jogador contra abuso, e cada um é contado por jogador e por operação:

Limite	Valor	Resposta ao estourar
Depósitos criados	10 por hora	429 rate_limited
Saques pedidos	3 por hora	429 rate_limited

Como eles funcionam:

• A ficha só é gasta depois que o corpo foi validado: um 400 não consome ficha.
• Um replay de idempotência (mesma chave, mesma resposta) não chega ao balde: não consome ficha.
• Cada ficha volta aos poucos: 1 ficha a cada 6 minutos no depósito e 1 a cada 20 minutos no saque. O Retry-After pode ser, por isso, de vários minutos. Não repita em laço: mostre ao jogador "tente mais tarde" e guarde o pedido.
• Se o limitador estiver fora, a resposta é 503 service_unavailable (nunca "sem limite"). Repita com a mesma chave.
• O limite por jogador é uma proteção do Dracma e é anterior às regras da operação (limites de valor e frequência por janela), que respondem 422. Veja Decisão, limites e regras.

Tamanhos e formatos¶

Item	Limite
Corpo da requisição	64 KiB na API (1 MB na entrada pública, que corta antes)
amount.amount	até 38 dígitos, sem zeros à esquerda
limit de listagem	1 a 200 (padrão 50)
external_id	1 a 64 caracteres [A-Za-z0-9_.:-]
player.external_ref	1 a 64 caracteres [A-Za-z0-9_.:-]
Idempotency-Key	16 a 128 caracteres [A-Za-z0-9_.:-]
Dracma-Key-Id	key_test_ ou key_live_ + 1 a 64 caracteres [A-Za-z0-9]
expires_in_seconds (depósito)	300 a 86.400 (padrão 1.800)
metadata	até 20 chaves
player.name	até 120 caracteres
player.email	até 254 caracteres
player.device_id	até 128 caracteres
player.document.number	CPF e CNPJ: só dígitos, de 11 a 14; outros documentos: até 32 caracteres
destination.pix.key	1 a 140 caracteres
justification de POST /rules/change-requests	1 a 1.000 caracteres
justification de POST /withdrawals/{id}/recall	até 1.000 caracteres
object_id e after de GET /events	até 64 caracteres (after com prefixo evt_)
Chaves de API ativas por operação	2

O contrato define até 256 caracteres por valor de metadata. A API hoje confere apenas o número de chaves e o tamanho total do corpo; respeite os 256 caracteres, que é o contrato.

Prazos fixos¶

Prazo	Valor
Janela do Dracma-Timestamp	±300 s
Retenção do nonce	600 s
Retenção da resposta de idempotência	30 dias
Reserva de uma chave em execução	30 s
Orçamento de resposta de POST /deposits	cerca de 7 s, depois 202
Folga depois de expires_at antes de expirar o depósito	2 minutos
Tempo de espera do pay de sandbox	até 3 s

Exemplos¶

Lote de 150 saques de uma só vez, com uma chave de escrita (50/s, rajada 100):

chamadas 1 a 100   → passam (o balde estava cheio)
chamada 101        → 429 rate_limited, Retry-After: 1
depois de ~1 s     → mais 50 chamadas passam, e assim por diante

Em vez de disparar, ponha os pedidos numa fila e consuma a 20 por segundo, bem abaixo do teto. Cada pedido volta a ser uma chamada assinada nova.

Quarto saque de uma hora para o mesmo jogador:

POST /v1/withdrawals   (player.external_ref = "u-1", 4º pedido na mesma hora)
→ 429 rate_limited, Retry-After: 1200

Erros e casos de borda¶

Situação	Resposta	O que fazer
Balde de IP, chave, operação ou listagem vazio	429 rate_limited + Retry-After	Espere e repita com a mesma Idempotency-Key; o 429 libera a chave e nunca duplica
Limite por jogador estourado	429 rate_limited + Retry-After longo	Mostre "tente mais tarde" ao jogador; não faça laço
20 falhas de assinatura por minuto do mesmo IP	429 no lugar de 401	Corrija a assinatura ou a chave
Limitador indisponível	503 service_unavailable + Retry-After: 1	Espere e repita
Corpo acima de 64 KiB	413 validation_failed	Reduza o corpo
Corpo acima de 1 MB	413 sem corpo problem+json, da borda	Reduza o corpo

Um laço de 429 sem espera piora o problema: respeite o Retry-After, use backoff com jitter e limite as tentativas (Idempotência e repetição).

Veja também¶

• Erros
• Idempotência e repetição
• Paginação e filtros
• Convenções HTTP
• Regras (API)
• Decisão, limites e regras