Formato de Erro
Todos os erros seguem o mesmo formato JSON:{
"error": {
"code": "error_code",
"message": "Descrição legível do erro"
}
}
Erros de Autenticação
| Status | Código | Descrição |
|---|---|---|
401 | missing_authorization | Header Authorization ausente |
401 | invalid_authorization | Header inválido; use Authorization: Bearer YOUR_API_KEY |
401 | invalid_api_key | Chave não encontrada |
403 | api_key_revoked | Chave revogada no dashboard |
403 | account_not_fully_verified | Conta sem cadastro completo ou sem KYC aprovado |
429 | rate_limit_exceeded | Limite de requisições excedido |
Erros de Cobranças
| Status | Código | Descrição |
|---|---|---|
400 | invalid_amount | amount deve ser inteiro positivo em centavos |
400 | description_required | description é obrigatória |
400 | customer_name_required | customerName é obrigatório |
400 | customer_document_required | customerDocument é obrigatório |
400 | invalid_customer_document | CPF ou CNPJ inválido |
400 | invalid_customer_email | E-mail inválido |
400 | invalid_parameter | Parâmetro de consulta inválido na lista |
422 | amount_below_minimum | Valor abaixo do mínimo de R$ 5,00 |
404 | charge_not_found | Cobrança não encontrada |
502 | provider_rejected | A adquirente recusou a cobrança |
502 | charge_creation_uncertain | A adquirente não confirmou a criação |
503 | provider_unavailable | Adquirente indisponível no momento |
Erros de Saques
| Status | Código | Descrição |
|---|---|---|
400 | invalid_amount | Valor deve ser positivo |
400 | invalid_pix_key | pixKey ausente ou inválida para o tipo |
400 | invalid_pix_key_type | pixType inválido. Aceitos: cpf, cnpj, email, phone, random |
422 | amount_below_minimum | Valor abaixo do mínimo de saque |
422 | insufficient_balance | Saldo disponível insuficiente |
422 | amount_below_fee | Taxa maior que o valor solicitado |
404 | payout_not_found | Saque não encontrado |
Boas Práticas
Sempre verifique o campo
error.code (não error.message) para tratar erros programaticamente, pois as mensagens podem mudar.const response = await fetch('https://api.visepag.com/v1/payouts', {
method: 'POST',
// ...
});
if (!response.ok) {
const { error } = await response.json();
switch (error.code) {
case 'insufficient_balance':
console.log('Saldo insuficiente para o saque');
break;
case 'rate_limit_exceeded':
// Aguardar e tentar novamente
break;
default:
console.error(error.message);
}
}