Erros e o que fazer
Toda resposta de erro vem em JSON, com uma única chave error e uma frase em português explicando o que faltou. O código HTTP diz de quem é o problema: 4xx é algo na sua requisição, 5xx é do nosso lado.
O que cada código significa?
| Código | Mensagem | Causa e correção |
|---|---|---|
401 | Token de ingestão ausente. | O cabeçalho Authorization não chegou. Verifique se escreveu Bearer antes do token, com um espaço. Se você usa curl -L ou n8n com o domínio antigo, o redirecionamento derruba o cabeçalho: use imobiliq.com.br. |
401 | Token de ingestão inválido. | O token chegou mas não corresponde a nenhuma conta. Copie de novo em Configurações, Integrações, sem espaços nas pontas. |
400 | Campo 'nome' é obrigatório. | O corpo não trouxe nome, ou trouxe vazio. Se o seu formulário separa nome e sobrenome, junte antes de enviar. |
400 | Informe ao menos 'telefone' ou 'email'. | Sem um dos dois não há como atender o lead. O telefone é o preferido: é ele que liga o lead à conversa do WhatsApp. |
400 | JSON inválido. | O corpo não é um JSON válido. Confira se o cabeçalho Content-Type: application/json está presente e se não sobrou vírgula no fim do objeto. |
429 | Limite de N leads no mês atingido. | O plano da conta chegou ao teto de leads do mês. O lead não entrou. Faça upgrade do plano ou espere o próximo ciclo. |
500 | Falha ao registrar o lead. | Erro do nosso lado. Guarde o corpo enviado e tente de novo em alguns minutos; se persistir, abra um chamado pelo Suporte com o horário exato da tentativa. |
O que parece erro mas não é
Resposta 200 com duplicado: true. Significa que aquele telefone já é um lead em atendimento, e as informações novas foram somadas à ficha em vez de criar um card repetido. É o comportamento correto, e o id devolvido é o do lead existente.
corretor_id nulo na resposta 201. O lead entrou, mas a fila não tinha corretor disponível para receber. Ele aparece como Sem corretor no painel, para alguém assumir. Vale conferir se a fila padrão tem membros ativos.
Como testo a minha integração?
Rode a requisição abaixo com o seu token e um telefone que você controla. O -i mostra o código HTTP junto com o corpo, que é o que importa para diagnosticar.
curl -i -X POST https://imobiliq.com.br/api/ingest/leads \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"nome":"Teste da Integracao","telefone":"+5547999990000"}'Como não perder lead quando a API falhar?
Nunca deixe o envio ao CRM bloquear o formulário do visitante. Grave o lead do seu lado primeiro, responda ao usuário, e mande para o ImobiliQ em seguida. Se a chamada falhar, registre o erro e tente de novo mais tarde: reenviar o mesmo telefone não cria card duplicado.