Problemas comuns
Erros de autenticação
A resposta vem em texto puro, só com o código:
| Status | Código | O que fazer |
|---|---|---|
| 401 | no_token_provided | Envie o header Authorization: Bearer lsk_api_.... Confira se o seu cliente HTTP não está removendo o header em redirecionamentos. |
| 401 | error_api_key_invalid | Confira se a chave foi copiada inteira, começando por lsk_api_, sem espaços nem quebra de linha. Confira também o ambiente: chave de homologação não vale em produção. |
| 401 | error_api_key_revoked | A chave foi revogada pelo dono, pelo administrador ou substituída por uma nova. Pegue a chave atual com o dono (API → Gerenciar) ou gere outra. |
| 401 | error_api_key_expired | A validade passou. Gere uma nova chave e troque no sistema. |
| 401 | error_api_key_user_inactive | O usuário dono foi desativado. Reative-o ou gere a chave em outro usuário. |
| 403 | error_api_key_no_access | O perfil do dono perdeu o menu Integração API. O administrador devolve o menu em Administração › Perfis; a chave volta a funcionar sem precisar gerar outra. |
| 403 | error_api_key_companie_inactive | A empresa não está ativa no LeadSim. Fale com o suporte. |
| 403 | error_api_key_forbidden_route | A rota não faz parte da API de integração. Veja 403 em uma rota que existe no LeadSim. |
| 429 | error_api_key_rate_limited | Limite de requisições. Veja 429. |
| 503 | error_api_key_unavailable | Falha temporária ao validar a chave. Repita a requisição depois de alguns segundos. |
Não vejo o menu Integração API
A tela em Gestão da Conta › Configurações e a opção API → Gerenciar no menu do avatar aparecem só para perfis com o menu Integração API. Peça ao administrador da empresa para liberar o menu no seu perfil, em Administração › Perfis. Veja Quem pode gerar chave.
O botão Copiar chave não aparece
Ele aparece só para o dono da chave e só na chave ativa. Se você é o dono e a chave está ativa, ela foi criada antes de o LeadSim guardar a cópia cifrada e não pode ser copiada de novo. Gere uma nova chave (Gerar nova chave) e troque no sistema; a anterior é revogada sozinha.
403 em uma rota que existe no LeadSim
A chave de API acessa só as rotas da Referência de rotas. Outras rotas que as telas do LeadSim usam respondem 403 error_api_key_forbidden_route, mesmo que o usuário tenha acesso à tela. Procure na referência uma rota equivalente; se não houver, o recurso não está disponível pela API de integração.
Se a rota está na referência e mesmo assim vem 403, confira o código do corpo: error_api_key_no_access é menu do perfil, error_api_key_companie_inactive é a empresa, e um 403 com outro código (por exemplo error_funnel_access_denied) é regra de negócio da rota, como um funil não liberado para o dono da chave.
429: limite de requisições
São 300 requisições por minuto por chave e 1.500 por empresa. A resposta 429 traz Retry-After e os headers RateLimit-*; espere o tempo indicado antes de repetir.
- Espace importações e sincronizações iniciais em lotes abaixo do limite.
- Em listagens, aumente
takeem vez de fazer muitas chamadas pequenas. - Se duas integrações usam a mesma chave, separe em dois usuários: o limite por chave deixa de ser disputado. Veja Usuário dedicado para a integração.
400 ValidationError
O corpo ou um parâmetro não passou na validação. O JSON de resposta diz, em validation, o campo e o motivo (tipo errado, obrigatório ausente, valor fora da lista). Confira o schema da rota na referência ou teste a mesma chamada no Swagger, que mostra o erro completo.
Em rotas filterAdvanced, lembre que vários arrays de filtro precisam ir sempre, nem que vazios ([]); a referência marca quais. Sem eles a resposta pode ser 500 em vez de 400.
409 em criação
Regra de negócio: o registro referenciado não existe na empresa (error_person_id_not_exist, error_funnel_step_id_not_exist), há duplicidade (contato com o mesmo CPF/CNPJ, e-mail ou WhatsApp; proposta que já virou contrato) ou o status atual não permite a operação (faturar contrato que não está Aberto). O código está na tabela Respostas da rota, na referência.