Política de Reenvio

Se seu endpoint retornar um código retentável ou não responder dentro do timeout da chamada HTTP(30 segundos), o Pinbank reagenda a entrega automaticamente, com backoff exponencial e jitter.

Classificação de erros

Resposta do seu endpoint	Comportamento
`2xx`	Sucesso — entrega concluída.
`408`, `429`, `500`, `502`, `503`, `504`	Retentável — nova tentativa agendada com backoff.
Timeout / erro de conexão	Retentável — nova tentativa agendada com backoff.
`4xx` (exceto `408`/`429`)	Não retentável — entrega finalizada como falha permanente, sem novas tentativas.

Configuração padrão

Pode ser personalizada na configuração do seu webhook (veja Configurando o webhook):

Parâmetro	Valor padrão	Efeito
`MaxTentativas`	`5`	Número total de tentativas de entrega, incluindo a inicial (1 entrega inicial + 4 retentativas).
`AtrasoInicialMs`	`60000` (1 min)	Atraso antes da 1ª retentativa.
`MultiplicadorBackoff`	`2.0`	Fator de multiplicação do atraso a cada retentativa.
`AtrasoMaximoMs`	`3600000` (60 min)	Teto para o atraso entre tentativas, mesmo com backoff exponencial.

Sequência de tentativas com a configuração padrão

Tentativa	Atraso base	Com jitter ±20% (faixa aproximada)
1ª (entrega inicial)	imediato	—
2ª	1 min	48s – 72s
3ª	2 min	96s – 144s
4ª	4 min	192s – 288s
5ª	8 min	384s – 576s

Com a configuração padrão (MaxTentativas: 5), a 5ª tentativa é a última — esgotada ela, a entrega é marcada como falha definitiva (cerca de 15 minutos após a entrega inicial). Aumentar o número de tentativas na configuração do seu webhook estende a sequência; o atraso continua dobrando a cada tentativa, até o teto configurado.

O jitter aleatório de ±20% evita que múltiplas entregas retentem exatamente ao mesmo tempo e sobrecarreguem seu endpoint (efeito thundering herd).

Esgotadas as tentativas

Se todas as retentativas se esgotarem, ou o seu endpoint responder com um 4xx permanente, a entrega é marcada como falha definitiva. Entre em contato com o suporte Pinbank pra consultar o status ou solicitar o reenvio manual — veja Consultando e reenviando entregas.

Idempotência é obrigatória

A entrega garantida é at-least-once, nunca exactly-once — o mesmo evento pode chegar mais de uma vez, mesmo sem falha (reprocessamentos, retentativas manuais). Processe cada entrega de forma idempotente usando EventId/Webhook-Id.

Classificação de erros#

Configuração padrão#

Sequência de tentativas com a configuração padrão#

Esgotadas as tentativas#

Idempotência é obrigatória#

Classificação de erros

Configuração padrão

Sequência de tentativas com a configuração padrão

Esgotadas as tentativas

Idempotência é obrigatória