Limites

Os tetos desta página são valores, não campos. Eles mudam raramente e, quando mudarem, entram no changelog.

Chamadas por minuto

O limite é por chave de API e separado por tipo de chamada:

A janela é fixa de 60 segundos, e não deslizante: o contador zera na virada do minuto.

Toda resposta traz três headers com o estado do balde:

• X-RateLimit-Limit: o teto da classe.
• X-RateLimit-Remaining: quantas chamadas sobram nesta janela.
• X-RateLimit-Reset: o instante em que o contador zera, em segundos desde a época Unix.

Estourou, a resposta é 429 rate_limited com o header Retry-After em segundos. Espere esse tempo antes da próxima tentativa. Não faça backoff cego: o Retry-After já é o número certo, e insistir antes dele só gasta mais 429.

Dois usos que costumam bater no teto e não precisam: pesquisar o status de uma cobrança em laço apertado (use webhooks) e listar tudo de novo a cada minuto (use os filtros de data).

Tamanho do corpo

O corpo de uma requisição em /v1 vai até 256 KB. Acima disso a requisição é cortada antes de chegar no handler.

Na prática só metadata chega perto: ela aceita no máximo 20 chaves, cada chave até 40 caracteres, cada valor até 500 caracteres, e 4 KB no total. Uma lista de itens vai até 50 entradas.

Faixas de valor

Valor de uma cobrança: de R$ 1,00 a R$ 100.000,00. Em centavos, de 100 a 10000000. Fora disso é 400 amount_too_small ou 400 amount_too_large.

A taxa nunca pode consumir a cobrança inteira. Um valor tão baixo que o líquido ficaria zero também responde 400 amount_too_small, mesmo estando acima de R$ 1,00.

Valor de um saque: mínimo de R$ 1,00, e o valor mais a taxa precisam caber no saldo disponível. Pode existir ainda um limite diário na sua conta, em valor e em quantidade; quando bate, a resposta é 409 daily_limit_exceeded com o limite e o usado em details.

Faixa de prazo

O prazo de expiração pedido na criação da cobrança vai de 5 minutos a 30 dias, em segundos: de 300 a 2592000. O padrão é uma hora. Fora da faixa é 400 invalid_expires_in.

Esse prazo é um pedido, e o processador pode encurtá-lo ou estendê-lo. A data que vale é a que volta na resposta. Detalhes em Expiração.

Próximo passo

Fundamentos fechados. Siga para Cobranças, o recurso principal da API.

Referência: Cria uma cobrança PIX.