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 |