Erros HTTP

HTTP 400 — Validação ou bloqueio

Erro de validação no payload ou pagamento bloqueado por regra interna.

{ "error": "Recusado por análise de risco" }

{
  "errors": {
    "threeDSecure": ["Cavv, Eci e Version são obrigatórios para pagamento 3DS."]
  }
}

{
  "errors": {
    "amount": ["Este campo é obrigatório."]
  }
}

Causas comuns de HTTP 400

Mensagem de erro	Causa	Solução
`"Recusado por análise de risco"`	Fraude detectada	Não revelar ao usuário — exibir mensagem genérica
`"Cavv, Eci e Version são obrigatórios..."`	`threeDSecure` incompleto	Verificar se `onSuccess` foi chamado antes do checkout
`"Este campo é obrigatório"`	Campo faltando no payload	Verificar campos obrigatórios na referência de request
`"Seller not found"`	`user` (Merchant ID) inválido	Verificar Merchant ID com a equipe Cakto
`"docType inválido"`	`docType` com letra maiúscula	Usar `"cpf"` ou `"cnpj"` (minúsculas)

HTTP 401 — Não autenticado

{ "detail": "Authentication credentials were not provided." }

Verifique o header Authorization: Token {API_TOKEN}.

HTTP 403 — Permissão negada

{ "detail": "You do not have permission to perform this action." }

O Merchant ID no campo user não corresponde às credenciais fornecidas.

HTTP 429 — Rate limit

Muitas requisições em curto período.

Estratégia recomendada: Retry com backoff exponencial.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options)
    if (response.status !== 429) return response

    const delay = Math.pow(2, attempt) * 1000  // 1s, 2s, 4s
    await new Promise(resolve => setTimeout(resolve, delay))
  }
  throw new Error('Rate limit excedido após 3 tentativas')
}

HTTP 500 / 502 — Erro interno

Erro temporário no servidor da Cakto.

Comportamento recomendado:

Logar o erro com o payload completo
Aguardar 5–10 segundos
Tentar novamente (máximo 3 vezes)
Se persistir, exibir mensagem genérica e notificar o suporte

// Verificar se é seguro fazer retry
function isSafeToRetry(status) {
  return status === 429 || status >= 500
}

Para erros 5xx, verifique se o pagamento não foi processado antes de tentar novamente — para evitar cobranças duplicadas. Consulte o status pelo postbackUrl (webhook) ou pelo ID da transação se disponível.

Timeout de rede

Configure um timeout razoável para cada tipo de chamada:

Chamada	Timeout recomendado
Token 3DS (`GET /api/3ds/token/`)	10 segundos
Checkout (`POST /api/checkout/`)	30 segundos
SDK 3DS `bpmpi_authenticate()`	90 segundos (global)

Erros HTTP

On this page