Erros - Flare DOCS

Formato de Erro

Todos os erros seguem o mesmo formato JSON:

{
  "error": {
    "code": "error_code",
    "message": "Descrição legível do erro"
  }
}

Alguns erros incluem campos extras com contexto adicional:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance",
    "available_balance": 50.00
  }
}

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_disabled`	Chave desativada no dashboard
`403`	`api_key_revoked`	Chave revogada 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);
  }
}