Erros mais comuns

Este guia aborda os erros mais frequentes que pode encontrar ao utilizar o Conviro e como os resolver.

HTTP 401 -- Unauthorized

Significado: A sua chave de API ou o token de sessão é inválido ou expirou.

Causas e soluções:

• A chave de API está incorreta -- verifique a chave em Dashboard -> Settings -> API Keys
• A chave de API foi revogada -- gere uma nova chave e atualize a sua integração
• A sessão expirou -- termine sessão no painel e volte a iniciar sessão
• Falta o cabeçalho Authorization -- certifique-se de que o seu pedido à API inclui Authorization: Bearer sk_your_key

HTTP 403 -- Forbidden

Significado: Não tem permissão para aceder a este recurso.

Causas e soluções:

• Domínio não permitido -- adicione o domínio do seu site em Dashboard -> Assistants -> Your Bot -> Channels -> Allowed Domains
• Limite do plano atingido -- está a tentar utilizar uma funcionalidade que não está disponível no seu plano atual (por exemplo, WhatsApp no Starter)
• Restrição de função -- a sua função na equipa (Agent) pode não ter permissão para esta ação; peça a um Admin ou a um Owner
• O bot está inativo -- ative o bot em Dashboard -> Assistants

HTTP 404 -- Not Found

Significado: O recurso solicitado não existe.

Causas e soluções:

• Endpoint errado -- consulte a documentação da API em /developers para obter os URL corretos
• Recurso eliminado -- o chatbot, a sessão ou o contacto foi eliminado
• Erro de escrita no ID -- verifique o ID do recurso no URL do seu pedido

HTTP 429 -- Too Many Requests (limite de pedidos)

Significado: Excedeu o limite de pedidos à API do seu plano.

Causas e soluções:

• Verifique os cabeçalhos de limite de pedidos na resposta:

X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

• Reduza a frequência dos pedidos -- adicione intervalos ou agrupe as operações
• Mude para um plano superior -- os planos superiores têm limites de pedidos mais elevados
• Coloque as respostas em cache -- evite repetir o mesmo pedido várias vezes

Limites de pedidos por plano:

Erros de CORS

Significado: O navegador está a bloquear um pedido de origem cruzada (cross-origin).

Sintoma: Vê na consola do navegador um erro como Access to XMLHttpRequest has been blocked by CORS policy.

Causas e soluções:

• Domínio do widget não permitido -- adicione o seu domínio à lista Allowed Domains
• Conteúdo misto -- se o widget for carregado por HTTPS, certifique-se de que o seu site utiliza HTTPS (e não HTTP)
• Interferência de proxy ou CDN -- verifique se a sua CDN está a remover os cabeçalhos CORS

Falhas na entrega de webhooks

Significado: O Conviro enviou um webhook, mas o seu servidor não respondeu com um código de estado 2xx.

Causas e soluções:

• O servidor está inativo -- verifique se o seu endpoint de webhook está em execução e acessível
• Tempo limite excedido -- o Conviro aguarda 10 segundos por uma resposta. Certifique-se de que o seu endpoint responde rapidamente
• Problema com o certificado SSL -- o seu endpoint tem de ter um certificado SSL válido (não são aceites certificados autoassinados)
• Bloqueio da firewall -- adicione o intervalo de IP do Conviro à lista de permissões da sua firewall
• URL errado -- confirme o URL do webhook em Dashboard -> Settings -> Webhooks

Política de novas tentativas: O Conviro repete os webhooks falhados 3 vezes com espera exponencial (1 min, 5 min, 30 min). Após 3 falhas, o webhook é marcado como falhado e recebe uma notificação por e-mail.

Consulte os registos de entrega em Dashboard -> Settings -> Webhooks -> Delivery Log.

Limite de mensagens atingido

Significado: Utilizou todas as suas mensagens mensais.

Causas e soluções:

• Free/Starter -- as conversas ficam suspensas até ao ciclo de faturação seguinte. Mude para um plano superior para obter mais mensagens.
• Pro/Growth -- ative a faturação de excedentes em Dashboard -> Settings -> Billing para comprar automaticamente blocos de mensagens adicionais.
• Verifique a utilização -- acompanhe o seu consumo em Dashboard -> AI Usage.

Sugestões gerais

• Verifique sempre a consola do navegador (F12) para detetar erros do lado do cliente.
• Nos erros de API, inspecione o corpo da resposta -- normalmente contém uma mensagem de erro descritiva.
• Consulte a página de estado do Conviro para saber se existem incidentes ou manutenções em curso.
• Se não conseguir resolver o problema, contacte [email protected] com os detalhes do erro, o ID do pedido (se disponível) e os passos para o reproduzir.