Skip to main content
Ao criar um lote, consulte error.code na resposta HTTP. Depois da criação, acompanhe o status do lote e de cada item junto dos campos lastErrorCode e statusReasonCode. Um motivo de processamento pendente pode aparecer em uma consulta HTTP 200.

Erros ao criar um lote

Envie uma criação de lote por vez por conta e aguarde a resposta HTTP antes da próxima. O HTTP 201 confirma a criação do lote. Os Pix do lote são processados depois e devem ser acompanhados por consulta. A rota permite até 10 solicitações de criação por minuto. Espaçar os envios por um segundo pode reduzir a concorrência, mas não substitui a espera pela resposta nem a cota da rota.

Exemplo de nova tentativa sem duplicar o Pix

Antes do primeiro envio, gere uma idempotencyKey para o lote e salve o corpo JSON completo no seu sistema. Use esse mesmo corpo nas novas tentativas, inclusive depois de reiniciar a aplicação. Se já tiver o batchId, consulte o lote. Por exemplo, se o primeiro envio usou "idempotencyKey": "payout-pedido-8472", mantenha payout-pedido-8472 e todos os campos do JSON nas tentativas seguintes. Carregue esse JSON como texto e passe-o para enviarLote(corpoOriginal). O exemplo em Node.js recebe o JSON original já salvo. Ele aguarda cada resposta, tenta novamente em caso de PAYOUT_BATCH_BUSY, P2028 ou timeout do cliente e recalcula a assinatura HMAC a cada envio.
HTTP 201 confirma a criação do lote. HTTP 200 indica que o lote já existia e retorna o mesmo batchId. Em ambos os casos, acompanhe os Pix pela consulta do lote. Se as tentativas se esgotarem, preserve a solicitação original para conciliação. Gerar uma chave nova pode criar outro lote.

Motivos no status de um item

Na consulta de saldo, HTTP 503 com BALANCE_UNAVAILABLE indica uma falha na leitura do saldo. Tente novamente apenas a consulta GET.
Não trate PIX_RESULT_PENDING como falha. Uma nova chave de idempotência pode criar uma segunda operação enquanto o primeiro resultado ainda está sendo confirmado.
Consulte o lote ou liste os itens para acompanhar o desfecho.

Avisos de revisão manual

Em ações sobre um lote existente, a API pode responder PIX_UNAVAILABLE com a mensagem “Lote indisponível para novas operações; revisão necessária.” Use o estado do item para confirmar se o Pix foi concluído, falhou ou segue em análise.
Last modified on November 13, 2026