Errori più comuni

Questa guida illustra gli errori più frequenti che puoi incontrare usando Conviro e come risolverli.

HTTP 401 -- Unauthorized

Significato: La tua chiave API o il token di sessione non è valido oppure è scaduto.

Cause e soluzioni:

• Chiave API errata -- controlla la chiave in Dashboard -> Settings -> API Keys
• Chiave API revocata -- genera una nuova chiave e aggiorna la tua integrazione
• Sessione scaduta -- esci dalla dashboard e accedi di nuovo
• Header Authorization mancante -- assicurati che la tua richiesta API includa Authorization: Bearer sk_your_key

HTTP 403 -- Forbidden

Significato: Non hai i permessi per accedere a questa risorsa.

Cause e soluzioni:

• Dominio non consentito -- aggiungi il dominio del tuo sito in Dashboard -> Assistants -> Your Bot -> Channels -> Allowed Domains
• Limite del piano raggiunto -- stai provando a usare una funzionalità non disponibile nel tuo piano attuale (ad esempio WhatsApp con Starter)
• Restrizione di ruolo -- il tuo ruolo nel team (Agent) potrebbe non avere i permessi per questa azione; rivolgiti a un Admin o a un Owner
• Il bot è disattivato -- attiva il bot in Dashboard -> Assistants

HTTP 404 -- Not Found

Significato: La risorsa richiesta non esiste.

Cause e soluzioni:

• Endpoint sbagliato -- consulta la documentazione API su /developers per gli URL corretti
• Risorsa eliminata -- il chatbot, la sessione o il contatto è stato eliminato
• Errore di battitura nell'ID -- controlla l'ID della risorsa nell'URL della richiesta

HTTP 429 -- Too Many Requests (limite di frequenza)

Significato: Hai superato il limite di frequenza delle richieste API previsto dal tuo piano.

Cause e soluzioni:

• Controlla gli header relativi al limite di frequenza nella risposta:

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

• Riduci la frequenza delle richieste -- inserisci delle pause o raggruppa le operazioni
• Passa a un piano superiore -- i piani superiori hanno limiti di frequenza più alti
• Metti in cache le risposte -- evita di ripetere più volte la stessa richiesta

Limiti di frequenza per piano:

Errori CORS

Significato: Il browser sta bloccando una richiesta cross-origin.

Sintomo: Nella console del browser compare un errore come Access to XMLHttpRequest has been blocked by CORS policy.

Cause e soluzioni:

• Dominio del widget non consentito -- aggiungi il tuo dominio all'elenco Allowed Domains
• Contenuti misti -- se il widget viene caricato in HTTPS, assicurati che il tuo sito usi HTTPS (non HTTP)
• Interferenza di proxy o CDN -- verifica se il tuo CDN rimuove gli header CORS

Webhook non consegnati

Significato: Conviro ha inviato un webhook, ma il tuo server non ha risposto con un codice di stato 2xx.

Cause e soluzioni:

• Server offline -- verifica che il tuo endpoint webhook sia attivo e raggiungibile
• Timeout -- Conviro attende una risposta per 10 secondi. Assicurati che il tuo endpoint risponda rapidamente
• Problema con il certificato SSL -- il tuo endpoint deve avere un certificato SSL valido (i certificati autofirmati non sono accettati)
• Blocco del firewall -- inserisci l'intervallo di IP di Conviro nella whitelist del tuo firewall
• URL errato -- verifica l'URL del webhook in Dashboard -> Settings -> Webhooks

Politica di ripetizione: Conviro riprova i webhook non riusciti 3 volte con attesa esponenziale (1 min, 5 min, 30 min). Dopo 3 tentativi falliti, il webhook viene contrassegnato come non funzionante e ricevi una notifica via e-mail.

Consulta i log di consegna in Dashboard -> Settings -> Webhooks -> Delivery Log.

Limite di messaggi raggiunto

Significato: Hai esaurito tutti i messaggi mensili.

Cause e soluzioni:

• Free/Starter -- le conversazioni vengono sospese fino al ciclo di fatturazione successivo. Passa a un piano superiore per avere più messaggi.
• Pro/Growth -- attiva la fatturazione del sovrautilizzo in Dashboard -> Settings -> Billing per acquistare automaticamente blocchi di messaggi aggiuntivi.
• Controlla il consumo -- monitora il tuo utilizzo in Dashboard -> AI Usage.

Consigli generali

• Controlla sempre la console del browser (F12) per gli errori lato client.
• In caso di errori API, esamina il corpo della risposta -- di solito contiene un messaggio di errore descrittivo.
• Consulta la pagina di stato di Conviro per verificare se sono in corso incidenti o manutenzioni.
• Se non riesci a risolvere il problema, scrivi a [email protected] indicando i dettagli dell'errore, l'ID della richiesta (se disponibile) e i passaggi per riprodurlo.