Skip to main content

​
Erros

A API do TroiaChat usa codigos HTTP padrao para indicar o resultado de cada requisicao.

​
Codigos de status

CodigoSignificadoDescricao
201CreatedRecurso criado com sucesso.
400Bad RequestDados invalidos no body da requisicao.
401UnauthorizedAPI Key ausente, invalida ou expirada.
403ForbiddenAPI Key nao tem permissao para esta operacao.
404Not FoundRecurso nao encontrado (ex: Step ID inexistente).
429Too Many RequestsLimite de requisicoes excedido.
500Internal Server ErrorErro interno do servidor.

​
Formato da resposta de erro

Todas as respostas de erro seguem o mesmo formato: 
{
  "success": false,
  "error": "Mensagem descritiva do erro"
}

​
Erros comuns e solucoes

Causa: O header X-API-Key nao foi enviado na requisicao.Solucao: Adicione o header com sua chave:
-H "X-API-Key: sua-chave-aqui"
Causa: A chave nao existe ou foi desativada no painel.Solucao: Verifique se a chave esta correta e ativa em Configuracoes > API Keys.
Causa: A chave atingiu sua data de expiracao.Solucao: Crie uma nova chave no painel do TroiaChat.
Causa: O stepId informado nao existe ou foi removido.Solucao: Verifique o ID da etapa no funil em CRM > Funis.
Causa: O body da requisicao contem campos com formato incorreto.Solucao: Verifique os tipos dos campos na referencia da API. A maioria dos campos e normalizada automaticamente, mas erros de formato em campos obrigatorios podem causar esta resposta.

​
Tratamento recomendado

Sempre verifique o campo success na resposta antes de processar os dados.
const response = await fetch(url, options);
const result = await response.json();

if (!result.success) {
  console.error(`Erro ${response.status}: ${result.error}`);
  // Trate o erro adequadamente
  return;
}

// Processar result.data normalmente
const lead = result.data;

​
Retry strategy

Para erros 429 (rate limit) e 500 (erro interno), recomendamos implementar retry com backoff exponencial: 
async function createLeadWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429 || response.status >= 500) {
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise((r) => setTimeout(r, delay));
      continue;
    }

    return response.json();
  }

  throw new Error("Max retries exceeded");
}