Documentação

Limites da API

Os limites da API v1 são valores iniciais publicados no contrato: cada resposta limitada traz cabeçalhos RateLimit e, se for preciso esperar, Retry-After; mudá-los não quebra a API.

Limites de taxa

Estes números são valores iniciais publicados no contrato. Eles se ajustam com a experiência; mudá-los não quebra a API.

Toda resposta de uma rota limitada traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Um 429 traz também Retry-After. Os valores são por janela; a rajada é o que se permite de uma vez sobre o ritmo sustentado.

Limites de taxa
Limites de taxa	Janela	Prática	Real	Rajada
Toda requisição autenticada, por chave	1 min	120	60	30
Pedir pagamentos (`POST /v1/spends`), por agente	1 min	20	10	5
Pedir pagamentos por dia, por agente	1 dia	1000	200	0
Conferir um pagamento (`POST /v1/spends/check`), por agente	1 min	60	30	10
Escritas de administração (agentes, regras, destinos, chaves), por chave	1 min	30	15	10
Rotacionar ou criar chaves por dia, por dono	1 dia	50	10	0
Controle do ambiente de prática (`/v1/test/*`), por dono	1 h	120	0	20
Requisições com chave inválida ou ausente, por IP	10 min	30	30	0

Cabeçalhos

Os cabeçalhos de limite que a API devolve são:

RateLimit-Limit
RateLimit-Remaining
RateLimit-Reset
Retry-After

Tamanhos

Valores máximos da requisição e de alguns campos.

Tamanhos
Tamanhos	Valor
Corpo da requisição	16 KiB
`memo`	280 caracteres
`client_reference`	64 caracteres
`destination`	253 caracteres
URL de `resource`	2048 caracteres
Itens por página (padrão)	10 itens
Itens por página (máximo)	50 itens
Espera longa (`wait_seconds`)	20 segundos
Memória da chave de idempotência (mínimo)	24 horas
Vida de uma aprovação pendente (padrão)	15 minutos (5-60)
Janela de aviso de compra duplicada	60 segundos
Vida de uma chave de prática (padrão)	90 dias
Vida de uma chave real (padrão)	30 dias
Convivência ao rotacionar uma chave (máximo)	7 dias

Cotas

Tetos de quantas coisas cada dono pode ter.

Cotas
Cotas	Valor
Agentes ativos em prática	5
Agentes ativos em real	10
Agentes arquivados	20
Chaves ativas por agente	3
Chaves de dono ativas	3
Destinos de webhook	10
Dias em que os eventos são guardados	30

Idempotência

Com a mesma chave e a mesma impressão (valor, moeda, destino e recurso), a API devolve o estado atual do mesmo pagamento com idempotent_replay: true, sem pagar de novo.
O memo e o client_reference não entram na impressão: um modelo os reescreve cada vez que tenta de novo.
A mesma chave com uma impressão diferente dá 409 idempotency_conflict; changed_fields diz o que mudou.
Um pagamento failed deixa a chave gasta: uma nova tentativa exige uma chave nova.

Webhooks

Tempo máximo de resposta do destino: 5 segundos.
Tentativas por entrega: 8, em cerca de 24 horas.
Após 20 falhas seguidas o destino é pausado e o dono é avisado.