Documentação / Erros comuns

Erros comuns

"Não autenticado. Envie o header X-API-Key…"

O servidor não reconheceu quem está chamando. Confira:

• o header é X-API-Key (não Authorization) e o valor é a chave inteira, com o ponto no meio;
• a chave não foi revogada — veja em painel → API keys;
• no Claude.ai/ChatGPT, que o login OAuth foi concluído e a conexão aparece em Conexões de IA.

invalid_api_key (401)

Chave inexistente ou desativada. Gere outra no painel — lembrando que a chave completa só aparece na criação.

insufficient_scope (403)

A chave é de nível read e as ferramentas precisam de write. Revogue e crie uma nova (chave nova já nasce write).

"Nenhuma rota ativa encontrada para: …" / no_routes_for_domain

O domínio final do link não pertence a nenhum marketplace configurado. Causas comuns:

• o marketplace não foi cadastrado (ou foi desativado) — veja Credenciais;
• o link é de um site que o produto não cobre;
• era um encurtador que não abriu. O servidor tenta resolver duas vezes, incluindo uma passada mais agressiva; se o destino não responder, a rota não é encontrada.

Pergunte "quais marketplaces eu tenho configurados?" — o get_bot_info mostra os domínios que convertem.

conversion_failed

A rota existe, mas a API do marketplace recusou a conversão. Quase sempre é credencial: expirada, sem permissão de API, ou de uma conta que ainda não foi aprovada no programa de afiliados. Use o testar do painel para confirmar de fora do chat.

search_failed e sites_failed

search_failed: nenhum marketplace configurado atende a busca — ou nenhum tem busca ativa (busca hoje é Shopee, AliExpress e Amazon; Kabum e Magalu quando pedidos pelo nome). sites_failed aparece na busca multi-site quando um deles falhou: os outros resultados vieram normalmente, e o produto pode existir no que falhou.

"Tool desconhecido"

O cliente pediu uma ferramenta fora das quatro do produto. Se isso apareceu num app conectado a vários servidores MCP, provavelmente ele mirou no servidor errado.

A IA não usa as ferramentas

Cite o servidor no pedido ("usa o MCP do Afiliado") e confirme que a conexão está ativa no app. No Claude.ai, o conector precisa estar ligado na conversa.

Nada acima resolveu

Traga o que apareceu (mensagem, marketplace e um link de exemplo) — com isso dá para dizer se é credencial, rota ou o marketplace fora do ar.