API

Códigos de erro

Códigos HTTP da API da CaedralPay, causas mais comuns e como resolver cada um.

Erros da API normalmente voltam no formato { "error": "mensagem" } com o código HTTP adequado à causa.

Erros de criação de ordem

Código Causa Como resolver
400 Campos ausentes ou inválidos em amountBRL, wallet ou webhookUrl Corrija o corpo conforme a Criar ordem
400 webhookUrl não é uma URL https Informe uma URL https válida e pública
400 token/chain fora da lista suportada Consulte GET /api/crypto/v1/chains
429 Rate limit por IP excedido Concentre a criação no seu backend; aguarde e tente novamente

Erros de seleção (payment intent)

Código Causa Como resolver
404 Intent expirado ou inexistente Crie um novo payment intent
409 Intent já confirmado Use a referência persistida na resposta da confirmação; ela não é devolvida no erro
400 Falta token/chain ou valor "auto" na confirmação Informe rede e ativo explícitos

Erros de pagamento on-chain

Situação Comportamento
Valor menor que o devido (underpay) Transação reverte integralmente
Token fora da allowlist Transação reverte
Ordem após a janela de pagamento Transação pode ser rejeitada; consulte payableUntil
Referência duplicada Registro rejeitado — cada ref é única
Cliente enviou a mais (overpayment) Excedente devolvido na mesma transação
Info

Nenhum desses cenários deixa valor retido no contrato: o saldo final é sempre zero, seja por execução bem-sucedida, seja por reversão.

Erros de infraestrutura

Código Causa
500 Erro interno — tente novamente com backoff
502/503 Cotação externa indisponível no momento