Saltar para o conteúdo principal
A API Enrow sinaliza problemas com códigos de status HTTP e um corpo de erro em JSON. Este guia explica os formatos de resposta de erro, os erros mais comuns e como corrigi-los, e como construir uma lógica de retentativa confiável. Para a lista completa de códigos, consulte Códigos de status.

​
Como é uma resposta de erro?

A maioria dos erros da API Enrow retorna um objeto JSON simples com um único campo message: 
{
  "message": "Human-readable error description"
}
A única exceção é um erro de crédito insuficiente (402) em endpoints individuais (buscar e-mail/telefone individual, verificar individual), que retorna um campo reason junto com success: 
{
  "reason": "Insufficient credits",
  "success": false
}
As respostas de erro nunca incluem os campos error, status ou retry_after. Leia o código de status HTTP para ramificar sua lógica e leia message (ou reason) para a descrição legível.

​
Quais são os erros mais comuns e como corrigi-los?

Os erros abaixo cobrem a grande maioria das requisições com falha. Cada um vem com o corpo da resposta que a API retorna e a correção.

​
Por que estou recebendo um 400 Bad Request?

Um 400 significa que o payload da requisição está malformado ou que falta um parâmetro obrigatório: 
{
  "message": "both company_domain and company_name are absent, input payload needs at least one of them"
}
Correção: Verifique se você está fornecendo todos os parâmetros obrigatórios para o endpoint. Por exemplo, Buscar E-mail exige fullname mais company_domain ou company_name.

​
Por que estou recebendo um 401 Unauthorized?

Um 401 significa que a chave de API está ausente ou inválida: 
{
  "message": "This apikey is not valid"
}
Correção: Verifique se a chave de API está correta e é enviada no cabeçalho x-api-key (não em Authorization). Consulte Autenticação para saber como passar a chave em cada requisição.

​
Por que estou recebendo um 402 Insufficient Credits?

Um 402 significa que a conta não tem créditos suficientes para executar a requisição: 
{
  "reason": "Insufficient credits",
  "success": false
}
Em endpoints em lote, o mesmo 402 é retornado com o formato padrão { "message": "..." }. Correção: Verifique o saldo de créditos no Dashboard ou via GET /account/info. Adicione créditos ou faça upgrade do plano em enrow.io/pricing. Consulte Créditos e cobrança para saber como os créditos são consumidos por endpoint.

​
Por que estou recebendo um 429 Rate Limit Exceeded?

Um 429 significa que muitas requisições foram enviadas em um curto intervalo: 
{
  "message": "Too Many Requests"
}
Correção: Aguarde e tente novamente com backoff exponencial. Consulte Limites de taxa para os limites por plano.

​
Por que estou recebendo um 500 Internal Server Error?

Um 500 significa que algo falhou no lado da Enrow: 
{
  "message": "An unexpected error occurred"
}
Correção: Tente novamente com backoff. Se o problema persistir, entre em contato com api@enrow.io.

​
Como trato erros no código?

Verifique o status HTTP antes de analisar o corpo de sucesso e, em seguida, gere um erro que carregue o código de status para que sua lógica de retentativa possa ramificar com base nele. O campo message contém a descrição da maioria dos erros, e reason a contém para as respostas 402 de endpoints individuais. 
async function findEmail(contact) {
  const response = await fetch('https://api.enrow.io/email/find/single', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.ENROW_API_KEY
    },
    body: JSON.stringify(contact)
  });

  if (!response.ok) {
    const body = await response.json();
    const error = new Error(`Enrow API error ${response.status}: ${body.message || body.reason}`);
    error.status = response.status;
    throw error;
  }

  return await response.json();
}

​
Como tento novamente requisições com falha?

Tente novamente apenas os erros que valem a pena repetir — 429 e 5xx — e aplique backoff exponencial entre as tentativas. Erros de cliente na faixa 4xx (exceto 429) indicam um problema com a própria requisição, portanto repeti-los não ajudará. 
async function requestWithRetry(fn, maxRetries = 3, baseDelay = 1000) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const isLastAttempt = attempt === maxRetries - 1;

      // Don't retry client errors (except rate limits)
      if (error.status >= 400 && error.status < 500 && error.status !== 429) {
        throw error;
      }

      if (isLastAttempt) throw error;

      const delay = baseDelay * Math.pow(2, attempt);

      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

​
Boas práticas

  • Não tente novamente erros 4xx (exceto 429) — corrija a requisição
  • Tente novamente erros 429 — aplique backoff com atrasos exponenciais antes de repetir
  • Tente novamente erros 5xx — com backoff exponencial
  • Use webhooks em vez de polling para evitar atingir os limites de taxa desnecessariamente — consulte Como os webhooks funcionam
  • Registre os erros com contexto — inclua o endpoint, os parâmetros e o timestamp para depuração

​
FAQ

Em endpoints individuais (buscar e-mail/telefone individual, verificar individual), um 402 retorna { "reason": "Insufficient credits", "success": false }. Em endpoints em lote, o mesmo 402 retorna o formato padrão { "message": "..." }. Ler tanto message quanto reason (como fazem os exemplos de código) cobre os dois casos.
Tente novamente erros 429 (limite de taxa) e 5xx (servidor) com backoff exponencial. Não tente novamente outros erros 4xx como 400, 401 ou 402 — eles indicam um problema com a requisição, a chave de API ou o saldo de créditos que repetir sozinho não resolverá.
Não. As respostas de erro nunca incluem os campos retry_after, error ou status. Use seu próprio backoff exponencial entre as retentativas. Consulte Limites de taxa para os limites que se aplicam ao seu plano.
Para a maioria dos erros, a descrição está no campo message. Para um 402 de crédito insuficiente em um endpoint individual, ela está no campo reason. Sempre ramifique sua lógica com base no código de status HTTP em vez de analisar o texto da mensagem.

​
Próximos passos

Códigos de status

A lista completa de códigos de status HTTP e seus significados.

Limites de taxa

Entenda os limites de requisição por plano para evitar erros 429.

Autenticação

Como passar sua chave de API no cabeçalho x-api-key.

Créditos e cobrança

Veja como os créditos são consumidos para cada endpoint.