Começar

Idempotência e novas tentativas

Repita qualquer chamada sem medo de cobrar ou sacar duas vezes.

Como funciona

Toda criação exige Idempotency-Key, de 8 a 128 caracteres visíveis. A Mainum guarda a chave junto com um resumo do corpo:

Mesma chave e mesmo corpo: você recebe o mesmo recurso, sem criar outro.
Mesma chave e corpo diferente: 409 com idempotency_conflict.
Uma chave usada não volta a valer para outra operação, nem depois de muito tempo.

Além disso, o external_id é único por conta: um segundo recurso com o mesmo valor recebe 409 com external_id_conflict.

Quando repetir

Resposta	O que fazer
Timeout ou conexão perdida	Repita com a mesma `Idempotency-Key`.
`503` `service_unavailable`	Repita com a mesma chave, esperando alguns segundos.
`429`	Espere o tempo de `Retry-After` e repita com a mesma chave.
`202` com status `CREATING`	A cobrança está sendo confirmada. Consulte pelo `id` depois do `Retry-After`; não crie outra.
`409` `charge_creation_in_progress`	Outra tentativa com a mesma chave ainda está em andamento. Consulte pelo `charge_id` devolvido.
`4xx` de validação	Não repita igual: corrija o pedido e use uma chave nova.

Saques em estado desconhecido

Se a instituição não confirmar um saque a tempo, ele fica UNKNOWN ou MANUAL_REVIEW com o valor reservado. Não crie outro saque para o mesmo pagamento: o resultado final chega por withdrawal.completed ou withdrawal.failed, e um saque que falha devolve o valor inteiro ao saldo.