Códigos de Erro

Todos os erros da API EloFiel seguem o mesmo envelope de resposta. O campo sucesso será false e a lista erros conterá as mensagens descritivas.

Formato de resposta de erro

{
  "sucesso": false,
  "dados": null,
  "mensagem": "Descrição geral do erro.",
  "erros": [
    "Mensagem detalhada do primeiro erro.",
    "Mensagem do segundo erro (validações múltiplas)."
  ]
}

---

Tabela de códigos HTTP

HTTP	Nome	Causa	Como tratar
400	Bad Request	Campo obrigatório ausente ou formato inválido (CPF, CNPJ, valor negativo)	Verificar os campos da requisição e corrigir antes de reenviar
401	Unauthorized	X-Api-Key ausente, inválida ou revogada	Verificar a configuração da chave de API
422	Unprocessable Entity	Regra de negócio violada (saldo insuficiente, mínimo não atingido)	Tratar especificamente conforme a mensagem; não reenviar sem correção
429	Too Many Requests	Rate limit excedido	Aguardar e reenviar com backoff exponencial
500	Internal Server Error	Erro interno no servidor	Registrar o erro, aguardar e reenviar; notificar se persistir

---

Erros de validação (HTTP 400)

Retornados quando a requisição contém campos inválidos ou ausentes.

Exemplo — campo obrigatório ausente:

{
  "sucesso": false,
  "dados": null,
  "mensagem": "Requisição inválida.",
  "erros": [
    "O campo CnpjLoja é obrigatório."
  ]
}

Exemplo — múltiplos erros de validação:

{
  "sucesso": false,
  "dados": null,
  "mensagem": "Requisição inválida.",
  "erros": [
    "O campo CpfCliente é obrigatório.",
    "O campo ValorVenda deve ser maior que zero."
  ]
}

Como tratar em código:

if (response.status === 400) {
  const resultado = await response.json();
  // Exibir todos os erros de validação
  resultado.erros.forEach(erro => console.error('Validação:', erro));
}

---

Erro de autenticação (HTTP 401)

Retornado quando a X-Api-Key está ausente, inválida ou revogada.

{
  "sucesso": false,
  "dados": null,
  "mensagem": "Não autorizado.",
  "erros": [
    "Não autorizado."
  ]
}

Chave revogada

Se você receber HTTP 401 em produção com uma chave que funcionava anteriormente, entre em contato com o suporte EloFiel imediatamente — a chave pode ter sido revogada por segurança.

---

Erros de regra de negócio (HTTP 422)

Retornados quando a requisição é tecnicamente válida, mas viola uma regra de negócio.

erros[0]	Situação	Solução
"Saldo insuficiente para resgate."	valorResgate maior que saldoCashback	Consultar saldo atualizado e ajustar o valor
"Cashback mínimo não atingido."	Campanha exige valor mínimo de resgate	Informar ao cliente o valor mínimo e oferecer apenas resgates acima dele

Exemplo:

{
  "sucesso": false,
  "dados": null,
  "mensagem": "Não foi possível processar o resgate.",
  "erros": [
    "Saldo insuficiente para resgate."
  ]
}

Como tratar:

if (response.status === 422) {
  const resultado = await response.json();
  const mensagemErro = resultado.erros[0];

  switch (mensagemErro) {
    case 'Saldo insuficiente para resgate.':
      // Atualizar saldo exibido e oferecer valor correto
      const saldoAtual = await consultarSaldo(cnpjLoja, cpfCliente);
      exibirSaldoAtualizado(saldoAtual.dados.saldoCashback);
      break;
    default:
      exibirMensagemErro(mensagemErro);
  }
}

---

Rate limit excedido (HTTP 429)

Retornado quando o limite de requisições é excedido. Atualmente aplicado apenas ao endpoint de login admin.

{
  "sucesso": false,
  "dados": null,
  "mensagem": "Limite de requisições excedido.",
  "erros": [
    "Muitas tentativas. Aguarde 1 minuto."
  ]
}

Consulte a documentação de rate limiting para implementar o retry correto.

---

Erro interno (HTTP 500)

Retornado por falhas inesperadas no servidor.

{
  "sucesso": false,
  "dados": null,
  "mensagem": "Erro interno do servidor.",
  "erros": [
    "Erro interno do servidor."
  ]
}

Como tratar:

if (response.status === 500) {
  // Registrar o erro com detalhes para diagnóstico
  console.error('Erro interno EloFiel:', {
    endpoint: request.url,
    timestamp: new Date().toISOString(),
    body: request.body,
  });

  // Para vendas: adicionar à fila de reprocessamento
  // Não bloquear o PDV
}

Registre o vendaId ou movimentacaoId quando disponível

Em erros de negócio, guarde o vendaId (agregador da venda — issue #3) ou o movimentacaoId dentro de beneficiosAplicados[] de transações anteriores relacionadas para facilitar o suporte.