Pular para o conteúdo principal

​
Estrutura de Erros

Quando ocorre um erro, a API retorna uma resposta com a seguinte estrutura: 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Descrição do erro",
    "details": {
      // Informações adicionais quando disponíveis
    }
  }
}

​
Códigos de Erro

​
Erros de Autenticação

Status: 401A chave de API está ausente, inválida ou expirada.
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
Solução: Verifique se a chave está correta e não expirou.
Status: 403A chave não tem permissão para este recurso.
{
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to access this resource"
  }
}
Solução: Verifique as permissões da sua chave no dashboard.

​
Erros de Validação

Status: 400Os dados enviados são inválidos.
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  }
}
Solução: Corrija os campos indicados em details.
Status: 400Um campo obrigatório não foi enviado.
{
  "error": {
    "code": "MISSING_FIELD",
    "message": "Required field missing",
    "details": {
      "field": "phone"
    }
  }
}
Solução: Inclua o campo obrigatório na requisição.

​
Erros de Recurso

Status: 404O recurso solicitado não existe.
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Lead not found"
  }
}
Solução: Verifique se o ID está correto.
Status: 409Um recurso com os mesmos dados já existe.
{
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "A lead with this phone number already exists"
  }
}
Solução: Use o endpoint de atualização ou use dados diferentes.

​
Erros de Rate Limit

Status: 429Muitas requisições em pouco tempo.
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": {
      "retry_after": 60
    }
  }
}
Solução: Aguarde o tempo indicado em retry_after (segundos).

​
Implementando Retry Logic

async function requestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const data = await response.json();
        const retryAfter = data.error?.details?.retry_after || 60;
        console.log(`Rate limited. Retrying in ${retryAfter}s...`);
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }

      if (response.status >= 500) {
        // Erro de servidor, tentar novamente com backoff exponencial
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Server error. Retrying in ${delay}ms...`);
        await new Promise(r => setTimeout(r, delay));
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

​
Boas Práticas

Sempre Verifique o Status

Nunca assuma que a requisição foi bem-sucedida. Sempre verifique o código HTTP.

Implemente Retry

Para erros 5xx e 429, implemente retry com backoff exponencial.

Log os Erros

Registre os erros para debugging e monitoramento.

Trate Casos Específicos

Implemente tratamento específico para cada tipo de erro.