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
| Limite | Valor hoje | Se passar |
|---|---|---|
| Pedidos por chave | 120 por minuto | 429 muitas_requisicoes |
| Pedidos por conta (todas as chaves juntas) | 300 por minuto | 429 limite_vendedor |
| Cobranças criadas pela API | 100 a cada 10 minutos | 429 muitas_requisicoes |
| Pix pendentes (sem pagar) ao mesmo tempo | teto por conta | 429 limite_pendentes |
| Movimento da plataforma no banco | teto por minuto | 429 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ção | Resposta |
|---|---|
| Mesma chave e mesmo corpo, pedido já terminado | A mesma resposta da primeira vez (mesmo status HTTP) |
| Mesma chave e corpo diferente | 422 idempotency_key_reusada |
| Mesma chave enquanto o primeiro ainda está sendo feito | 409 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 |