Todos os erros seguem o mesmo formato JSON:
{
"error": {
"code": "error_code",
"message": "Descrição legível do erro"
}
}
{
"error": {
"code": "insufficient_balance",
"message": "Insufficient balance",
"available_balance": 50.00
}
}
Erros de Autenticação
| Status | Código | Descrição |
|---|
401 | unauthorized | Header Authorization ausente |
401 | invalid_api_key | Chave inválida ou sem prefixo flare_ |
403 | api_key_disabled | Chave desativada no dashboard |
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 | missing_id | ID da cobrança não informado |
404 | charge_not_found | Cobrança não encontrada |
Erros de Saques
| Status | Código | Descrição |
|---|
400 | invalid_amount | Valor deve ser positivo |
400 | missing_pix_key | pix_key e pix_key_type são obrigatórios |
400 | invalid_pix_key_type | Tipo inválido. Aceitos: cpf, cnpj, email, phone, random |
400 | below_minimum | Valor abaixo do mínimo de R$ 30,00 |
400 | insufficient_balance | Saldo insuficiente (retorna available_balance) |
400 | fee_exceeds_amount | Taxa maior que o valor solicitado |
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.flarepayments.com/v1/charges', {
method: 'POST',
// ...
});
if (!response.ok) {
const { error } = await response.json();
switch (error.code) {
case 'insufficient_balance':
console.log(`Saldo disponível: R$ ${error.available_balance}`);
break;
case 'rate_limit_exceeded':
// Aguardar e tentar novamente
break;
default:
console.error(error.message);
}
}
