Comece por aqui

Limites e repetição segura

Limites de pedidos que protegem a sua conta e a plataforma, e como repetir um pedido sem criar nada em dobro.

Limites de pedidos

LimiteValor hojeSe passar
Pedidos por chave120 por minuto429 muitas_requisicoes
Pedidos por conta (todas as chaves juntas)300 por minuto429 limite_vendedor
Cobranças criadas pela API100 a cada 10 minutos429 muitas_requisicoes
Pix pendentes (sem pagar) ao mesmo tempoteto por conta429 limite_pendentes
Movimento da plataforma no bancoteto por minuto429 banco_no_limite: tente em instantes

As respostas não trazem cabeçalhos de limite (X-RateLimit-* ou Retry-After). Ao receber 429, espere alguns segundos e tente de novo, aumentando a espera a cada nova falha.

Consultar uma cobrança pendente pergunta ao banco na hora, mas no máximo a cada 20 segundos por cobrança. Prefira o webhook a ficar consultando sem parar.

Repetição segura (Idempotency-Key)

Se a conexão cair no meio do pedido, você não sabe se a cobrança ou o saque foi criado. Mande o cabeçalho Idempotency-Key com um código seu (por exemplo o número do pedido): repetir o mesmo pedido com a mesma chave devolve a mesma resposta, sem criar outro.

Idempotency-Key: pedido-1042
  • Formato: de 1 a 80 caracteres entre letras, números e _ - : .
  • POST /charges: opcional. Valor fora do formato: 400 idempotency_key_invalida.
  • POST /withdrawals: obrigatória. Sem ela: 400 idempotency_key_obrigatoria.
  • Vale por chave de API. As respostas ficam guardadas por 7 dias.
SituaçãoResposta
Mesma chave e mesmo corpo, pedido já terminadoA mesma resposta da primeira vez (mesmo status HTTP)
Mesma chave e corpo diferente422 idempotency_key_reusada
Mesma chave enquanto o primeiro ainda está sendo feito409 em_andamento: tente de novo em instantes
Pedido recusado (dados inválidos, limites, antifraude)A chave fica livre para você corrigir e mandar de novo