Idempotência

Redes falham. Com Idempotency-Key você repete uma criação quantas vezes precisar sem duplicar pagamentos, pedidos ou recursos.

Como usar

Envie o cabeçalho Idempotency-Key com 8 a 255 caracteres, único por operação de negócio (ex.: pedido-1001-criar-pagamento ou um UUID guardado junto do seu pedido).
Em timeout, erro de rede, 5xx ou 409 IDEMPOTENCY_IN_PROGRESS, repita com a mesma chave e o mesmo corpo.
Para uma operação nova, use uma chave nova.

Regras

Situação	Resposta
Sem o cabeçalho	`400 IDEMPOTENCY_KEY_REQUIRED` (verificado depois da autorização e antes do corpo)
Chave fora de 8 a 255 caracteres	`400 VALIDATION_FAILED`
Mesma chave, mesmo corpo, primeira já concluída	Mesmo status e mesmo corpo da primeira resposta. Nas criações de catálogo, sessões, Payment Links, webhooks e API keys vem também o cabeçalho `idempotent-replayed: true`.
Mesma chave, corpo (ou recurso alvo) diferente	`409 IDEMPOTENCY_CONFLICT`
Mesma chave enquanto a primeira ainda executa	`409 IDEMPOTENCY_IN_PROGRESS` (repetível; tente de novo com a mesma chave)
A primeira falhou com erro do cliente (validação, não encontrado, proibido)	A chave é liberada: corrija e repita.
Pagamentos e reembolsos repetidos	Devolvem o mesmo resultado sem nova chamada ao provedor e sem novo lançamento no ledger.

A chave vale por seller e por operação e fica guardada por 24 horas; depois disso pode ser reutilizada.

Segredos exibidos uma única vez

Três criações revelam um segredo que a Wolf nunca guarda em claro. O replay devolve o mesmo recurso sem o segredo e com secret_already_revealed: true:

POST /v1/api-keys — secret (sk_test_...);
POST /v1/webhooks/endpoints no modo live e POST /v1/webhooks/endpoints/{id}/rotate-secret — signing_secret (whsec_live_...);
POST /v1/checkout-sessions — client_secret (csec_...).

Replay de POST /v1/api-keys http

HTTP/1.1 201 Created
idempotent-replayed: true
content-type: application/json

{"credential": {"id": "key_...", "status": "active", ...}, "secret_already_revealed": true}

Quem perdeu o segredo cria um recurso novo com uma chave de idempotência nova.

Operações que exigem Idempotency-Key

post /v1/api-keys — Criar API key
post /v1/checkout-sessions — Criar sessão de checkout
post /v1/offers — Criar oferta
post /v1/offers/{id}/bumps — Criar order bump
post /v1/orders — Criar pedido
post /v1/orders/{id}/cancel — Cancelar pedido
post /v1/orders/{id}/expire — Expirar pedido
post /v1/orders/{id}/payment-intents — Criar PaymentIntent do pedido
patch /v1/organizations/current — Atualizar a organização atual
post /v1/payment-intents — Criar PaymentIntent
post /v1/payment-intents/{id}/confirm — Confirmar PaymentIntent
post /v1/payment-intents/{id}/refunds — Reembolsar PaymentIntent
post /v1/payment-links — Criar Payment Link
post /v1/payouts — Solicitar saque sintético
post /v1/products — Criar produto
post /v1/products/{id}/access-links — Adicionar link de acesso
post /v1/public/checkout-sessions/{id}/pay — Pagar sessão de checkout
post /v1/reports/abandoned-checkouts/{leadId}/recovery-link — Gerar link de recuperação
post /v1/webhooks/deliveries/{id}/replay — Reenviar entrega (replay)
post /v1/webhooks/endpoints — Criar endpoint
post /v1/webhooks/endpoints/{id}/rotate-secret — Rotacionar signing secret
post /v1/webhooks/endpoints/{id}/test — Enviar evento de teste