Erros da API de pagamentos VwtlProxy

Referência dos erros implementados nas rotas de cobrança e verificação da VwtlProxy. O status HTTP indica o resultado da requisição; os códigos abaixo identificam a causa.

Formato de resposta

{
  "error": {
    "code": "session_required",
    "message": "Abra novamente a tela de pagamento para iniciar sua sessão."
  }
}

Quando aplicável, leia error.code e error.message. Uma rota indisponível também pode retornar uma mensagem sem código específico. Mensagem de erro, envio de hash ou falha de consulta não significam pagamento recebido.

Códigos e ações recomendadas

HTTP	Código	Como proceder
400	`invalid_json`	Corpo inválido. Envie JSON válido.
401	`session_required`	Abra novamente a tela de pagamento ou consulte GET /api/payments/config para iniciar a sessão privada do navegador. Não é necessário fazer login.
403	`origin`	Faça o pedido na mesma origem do site.
404	`not_found`	Confira o ID. Somente pedidos da sessão atual ou da conta legada já autenticada podem ser consultados.
409	`conflict`	A chave de idempotência já está associada a outro conteúdo. Recupere o pedido original ou gere uma chave para uma nova compra.
409	`transaction_reused`	Essa transação já pertence a outro pedido. Não tente utilizá-la novamente.
413	`too_large`	O corpo ultrapassa 8.192 bytes. Envie somente os campos previstos.
415	`content_type`	Use Content-Type: application/json nos pedidos POST.
422	`invalid_key`	A chave de idempotência deve ter 32 a 128 caracteres: letras, números, hífen ou sublinhado.
422	`invalid_transaction`, `invalid_txid`	Confira o hash público completo. Em métodos automáticos EVM, use 0x seguido de 64 caracteres hexadecimais.
422	`invalid_kind`, `invalid_order`	Use purchase ou recharge e somente os campos documentados para esse tipo de pedido.
422	`invalid_plan`, `invalid_product`, `invalid_quantity`	Use um plano e produto do catálogo e uma quantidade inteira dentro dos limites.
422	`invalid_amount`	Valores usam centavos inteiros. A recarga mínima é US$30,00.
422	`price_changed`	Atualize a cobrança para usar o catálogo oficial e a taxa de 4,99%. O servidor não aceita preços arbitrários.
429	`limit`	Aguarde antes de criar outra cobrança.
500	`invalid_catalog`, `invalid_clock`, `invalid_invoice`, `random_unavailable`	O servidor não conseguiu preparar ou validar a cobrança. Não envie fundos usando instruções incompletas. Tente novamente ou procure o suporte.
503	`method_unavailable`	O método, a carteira ou a rede não está disponível para essa operação. Escolha um método disponível.
503	`quote_unavailable`, `upstream_unavailable`	Não foi possível obter a cotação ou consultar a rede. Tente novamente depois.
503	`rpc_unavailable`, `rpc_malformed`, `unavailable`	Pagamento ou consulta indisponível. A falha não confirma o pagamento; evite enviar novamente se já existe uma transação.
`invalid_contact_email`	422	E-mail de contato ausente ou inválido.	Informe contactEmail válido antes de criar a cobrança.

Estado do pagamento e estado da requisição

A consulta bem-sucedida pode retornar um pedido ainda não pago. Somente status: paid confirma o recebimento validado.

Estado do pedido	Significado
`awaiting_payment`	Cobrança criada, aguardando uma transação.
`check`	Transação registrada e em verificação.
`confirm_check`	Transação localizada, aguardando confirmações da rede.
`manual_review`	Pagamento nessa rede exige conferência pelo suporte.
`needs_review`	Dados da transação precisam de análise. Não libere uma compra por esse estado.
`expired`	Cotação encerrada. Gere uma cobrança válida antes de enviar fundos.
`paid`	Recebimento confirmado na blockchain.

Os detalhes de verification, quando presentes, podem informar o motivo de uma verificação pendente ou recusada. Isso não substitui o estado final do pedido.

Se já enviou o pagamento

Não envie novamente apenas porque uma consulta falhou. Guarde o ID do pedido, a rede, a moeda e o hash público e contate support@vwtlproxy.com. Nunca forneça chave privada ou frase de recuperação.

Nos métodos automáticos, a transferência precisa conter a referência da cobrança. Pagamentos por Bitcoin, Solana, Tron e Stellar usam conferência manual. O cadastro visual não cria conta ou chave de API. A sessão de pagamentos é iniciada automaticamente pela configuração, sem login; o e-mail não libera pedidos de outra sessão.

Consulte o guia de integração e a API de pagamentos.