Erros

Toda resposta fora de 2xx usa o mesmo envelope. Programe contra error.code, que é estável; message é só informativa.

Envelope de erro http

HTTP/1.1 409 Conflict
x-request-id: req_4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b
content-type: application/json

{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "Idempotency key was already used with a different request.",
    "request_id": "req_4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b"
  }
}

request_id (também no cabeçalho x-request-id) identifica a requisição: informe-o ao suporte.
Códigos marcados como repetível podem ser tentados de novo com backoff — nas criações, com a mesma Idempotency-Key.
429 RATE_LIMITED traz Retry-After em segundos.
Erros internos nunca expõem detalhes: aparecem como 500 INTERNAL_ERROR.

Códigos

Tabela gerada do registro de erros da plataforma.

Código	HTTP	Significado
`IDEMPOTENCY_KEY_REQUIRED`	400	A operação exige o cabeçalho `Idempotency-Key`. “Idempotency-Key is required.”
`VALIDATION_FAILED`	400	Corpo, parâmetro ou cabeçalho inválido (formato, tamanho, campo desconhecido, documento com dígito verificador errado). Corrija a requisição; repetir igual falha de novo. “Request validation failed.”
`ADMIN_SESSION_REVOKED`	401	Exclusivo do Wolf Admin: a sessão administrativa foi encerrada. “Admin session is no longer active.”
`AUTHENTICATION_REQUIRED`	401	Sem credencial, credencial inválida, revogada ou vencida, ou uma chave `sk_live_` (não existe nesta edição). “Authentication required.”
`PAYMENT_DECLINED`	402	O pagamento foi recusado pelo provedor simulado. O PaymentIntent fica `failed` com `failure_code` (`CARD_DECLINED`, `INSUFFICIENT_FUNDS`). “Payment was declined.”
`ADMIN_MFA_REQUIRED`	403	Exclusivo do Wolf Admin: exige autenticação de dois fatores. “Platform Admin multi-factor authentication is required.”
`ADMIN_STEP_UP_REQUIRED`	403	Exclusivo do Wolf Admin: exige verificação recente de dois fatores. “A recent Admin multi-factor verification is required.”
`CAPTCHA_REQUIRED`	403	Só nas rotas públicas do checkout hospedado (abrir Payment Link, pagar e simular Pix): quando o ambiente tem o Cloudflare Turnstile, o servidor do checkout envia o token do widget no header `wolf-turnstile-token`. Token ausente, inválido, já usado ou de outra ação → 403. Obtenha um token novo (cada um vale uma vez, por até 300 s) e repita. “A valid human verification (Turnstile) token is required for this action.”
`FORBIDDEN`	403	A credencial não tem o escopo exigido pela rota, ou a operação exige sessão humana do app do seller (API keys, rotação de segredo, endpoint `live`). “You are not allowed to perform this action.”
`STEP_UP_REQUIRED`	403	Pela sessão do app do seller, reembolsos exigem reautenticação recente (senha ou TOTP há no máximo 10 minutos). Reautentique e repita com a mesma `Idempotency-Key`. API keys não passam por essa verificação. “A recent re-authentication is required for this action.”
`RESOURCE_NOT_FOUND`	404	O recurso não existe, pertence a outro seller ou a rota não existe nesta edição. A resposta é a mesma nos três casos. “Resource not found.”
`BUMP_NOT_AVAILABLE`	409	Um `bump_ids` enviado ao pagar a sessão ou criar o pedido não é um order bump ativo desta oferta (de outro seller, inativo, repetido, de outra oferta ou desconhecido), ou os order bumps estão desligados no ambiente (`CHECKOUT_BUMPS_ENABLED`). Nada foi criado nem cobrado: leia de novo os `bumps` da sessão e repita com uma seleção válida. “One or more selected order bumps are not available for this checkout; nothing was charged.”
`DISPUTE_EXCEEDS_NET_CAPTURED`	409	Operação sintética da Wolf: a disputa excede o valor líquido capturado. “Dispute amount exceeds the disputable captured amount.”
`IDEMPOTENCY_CONFLICT`	409	A mesma `Idempotency-Key` já foi usada com outro corpo (ou outro alvo). Use uma chave nova para uma operação nova. “Idempotency key was already used with a different request.”
`IDEMPOTENCY_IN_PROGRESS`repetível	409	Outra requisição com a mesma chave ainda está em andamento. Tente de novo em alguns segundos com a mesma chave. “An operation with this idempotency key is still processing.”
`INVALID_STATE_TRANSITION`	409	O estado atual do recurso não permite a operação (ex.: confirmar um PaymentIntent já pago, reembolsar um pagamento não capturado). “Resource state does not allow this operation.”
`PAYMENT_LIMIT_EXCEEDED`	409	O valor excede o limite de risco configurado para o seller. “Payment amount exceeds the configured risk limit.”
`PAYMENT_METHOD_NOT_ACCEPTED`	409	A oferta da sessão não aceita o método escolhido (`accepted_methods`): o pagamento é recusado antes de criar pedido ou cobrança. Use um dos métodos aceitos, que a sessão pública informa. “The offer of this checkout does not accept the chosen payment method; use one of its accepted methods.”
`PAYMENT_METHOD_UNAVAILABLE`	409	O método de pagamento está temporariamente desligado neste ambiente (kill switch `PIX_SIMULATION_ENABLED`): criar, confirmar, pagar ou simular um Pix responde 409, e o cartão de teste continua funcionando. Use outro método ou tente mais tarde. “This payment method is temporarily disabled in this environment; use another payment method.”
`PAYOUT_AMOUNT_EXCEEDS_AVAILABLE`	409	`POST /v1/payouts`: o valor do saque sintético excede o saldo disponível. Consulte o saldo e peça um valor menor. “The payout amount exceeds your available balance.”
`PAYOUT_BELOW_MINIMUM`	409	`POST /v1/payouts`: o saque sintético mínimo é `1000` (R$ 10,00). “The payout amount is below the minimum of R$ 10,00.”
`PAYOUT_EXCEEDS_AVAILABLE`	409	Operação sintética da Wolf: o repasse excede o saldo disponível. “Payout amount exceeds the seller available balance.”
`PRODUCT_ACCESS_LINK_LIMIT_REACHED`	409	O produto já tem 5 links de acesso (o máximo); remova um com `DELETE /v1/products/{id}/access-links/{linkId}` antes de adicionar outro. “The product already has the maximum of 5 access links; delete one before adding another.”
`PRODUCT_NOT_ACTIVE`	409	Uma oferta só pode ser ativada com o produto `active`. “Product must be active before its offer can be activated.”
`PROVIDER_STATE_UNKNOWN`	409	O estado no provedor é desconhecido e está em reconciliação. Não tente cobrar de novo: acompanhe o PaymentIntent. “Payment provider state is unknown and requires reconciliation.”
`REFUND_EXCEEDS_CAPTURED`	409	A soma dos reembolsos passaria do valor capturado. “Refund amount exceeds the refundable captured amount.”
`REFUND_FAILED`	409	O reembolso foi recusado pelo provedor simulado. “Refund could not be completed.”
`TENANT_SELECTION_REQUIRED`	409	A sessão do app do seller tem mais de uma organização: envie `wolf-organization-id`. “Select an organization for this request.”
`WEBHOOK_ENDPOINT_DISABLED`	409	O endpoint de webhook está desativado; reative-o antes de testar ou reenviar entregas. “Webhook endpoint is disabled; reactivate it before sending deliveries.”
`RATE_LIMITED`repetível	429	Muitas requisições na janela do escopo. Espere os segundos do cabeçalho `Retry-After` e tente de novo. “Too many requests.”
`INTERNAL_ERROR`repetível	500	Erro inesperado da Wolf. Pode ser repetido com a mesma `Idempotency-Key`; informe o `request_id` ao suporte se persistir. “Internal error.”
`ADMIN_SESSION_VERIFICATION_UNAVAILABLE`repetível	503	Exclusivo do Wolf Admin: verificação de sessão temporariamente indisponível. “Admin session verification is temporarily unavailable.”
`SERVICE_UNAVAILABLE`repetível	503	Dependência temporariamente indisponível. Pode ser repetido com a mesma `Idempotency-Key`. “Service temporarily unavailable.”

Recusa e estado desconhecido

Uma recusa de pagamento responde 402 PAYMENT_DECLINED e deixa o PaymentIntent failed com failure_code (CARD_DECLINED ou INSUFFICIENT_FUNDS nos cartões de teste). Um timeout do provedor não é recusa: o PaymentIntent fica processing e a reconciliação decide — nunca crie outro pagamento para o mesmo pedido enquanto isso. Veja Cartões de teste.