# Context pack: Risoluzione dei problemi Source: https://nordvec.com/it/docs/guides/troubleshooting Pack: https://nordvec.com/it/docs/packs/troubleshooting This pack bundles one Nordvec guide with the guides it builds on and the guides it links to, in reading order, so an assistant reading it meets no reference it cannot follow. ## Contents 1. [Errori e limiti di frequenza](https://nordvec.com/it/docs/guides/errors-and-rate-limits) (builds on) 2. [Risoluzione dei problemi](https://nordvec.com/it/docs/guides/troubleshooting) (this guide) 3. [Ricollega un connettore](https://nordvec.com/it/docs/guides/troubleshooting/reconnect-integration) (linked from this guide) 4. [Concedi le autorizzazioni mancanti](https://nordvec.com/it/docs/guides/troubleshooting/insufficient-scopes) (linked from this guide) 5. [Limite documenti raggiunto](https://nordvec.com/it/docs/guides/troubleshooting/document-limit) (linked from this guide) 6. [Limite di elaborazione giornaliera raggiunto](https://nordvec.com/it/docs/guides/troubleshooting/daily-processing-limit) (linked from this guide) --- # Errori e limiti di frequenza Source: https://nordvec.com/it/docs/guides/errors-and-rate-limits La singola busta di errore che ogni richiesta fallita restituisce, le intestazioni del limite di frequenza e come ritentare una scrittura in modo sicuro. Ogni endpoint fallisce allo stesso modo, quindi un client gestisce errori, limiti di frequenza e tentativi una volta sola e riutilizza quel codice ovunque, incluso su [MCP](/docs/guides/mcp). ## La busta di errore [#la-busta-di-errore] Ogni risposta non-2xx è un oggetto JSON: ```json { "defined": false, "code": "TOO_MANY_REQUESTS", "message": "Too many requests", "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 } } ``` * `code` è l'errore a livello HTTP, ad esempio `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BAD_REQUEST` o `TOO_MANY_REQUESTS`. * `data.reason`, quando presente, è un motivo più preciso leggibile dalla macchina come `auth.key_not_found` o `rate_limit.exceeded`. Fai branching su questo piuttosto che su `message`, che è per le persone e può cambiare. * `defined` è `true` quando l'operazione elenca quell'errore nella [riferimento API](/docs/api), e `false` per errori che qualsiasi richiesta può incontrare (autenticazione, limiti di frequenza, una rotta sconosciuta). * Un fallimento di validazione risponde `BAD_REQUEST` con i problemi in `data.formErrors` e `data.fieldErrors`. Ogni risposta include anche un `X-Request-ID`. Citalo quando contatti l'assistenza, così possiamo trovare quella richiesta esatta. ## Stati comuni [#stati-comuni] | Stato | Codice | Cosa fare | | ----- | ----------------------- | ---------------------------------------------------------------------------------- | | `400` | `BAD_REQUEST` | Correggi la richiesta; `data.fieldErrors` indica i campi | | `401` | `UNAUTHORIZED` | Invia una chiave o sessione valida | | `403` | `FORBIDDEN` | La chiave non ha lo scope o il ruolo richiesto dall'operazione | | `404` | `NOT_FOUND` | La risorsa non esiste, oppure non hai il permesso di vederla | | `409` | `CONFLICT` | Una scrittura duplicata è ancora in corso; riprova tra poco | | `413` | `PAYLOAD_TOO_LARGE` | Il corpo della richiesta supera 1 MB; suddividi un invio bulk in batch più piccoli | | `422` | `UNPROCESSABLE_CONTENT` | La richiesta è ben formata ma non può essere applicata | | `429` | `TOO_MANY_REQUESTS` | Attendi `Retry-After`, poi riprova | ## Limiti di frequenza [#limiti-di-frequenza] Ogni risposta indica il limite contro cui è stata conteggiata, in due forme: * le intestazioni `X-RateLimit-*`; * i campi strutturati IETF `RateLimit` (stato attuale: `r` sono le richieste rimanenti, `t` i secondi fino al reset della finestra) e `RateLimit-Policy` (la quota: `q` è il limite, `w` la finestra in secondi). Una `429` include anche `Retry-After` in secondi e `data.retryAfterMs`. Attendi almeno quel tempo prima della prossima richiesta; riprovare prima viene conteggiato e rifiutato di nuovo. ## Ripetizione sicura delle scritture [#ripetizione-sicura-delle-scritture] Un'operazione di scrittura che elenca un'intestazione `Idempotency-Key` nella [riferimento API](/docs/api) può essere ripetuta senza eseguire il lavoro due volte. Invia una chiave per ogni scrittura logica e ripeti la stessa chiave in ogni tentativo: * la stessa chiave con lo stesso corpo entro 24 ore riproduce la risposta memorizzata; * la stessa chiave con un corpo diverso viene rifiutata con `422`; * un duplicato che arriva mentre il primo è ancora in esecuzione riceve `409`. Un'operazione senza l'intestazione non è idempotente, quindi ripetila solo quando sai che il primo tentativo non è andato a buon fine. --- # Risoluzione dei problemi Source: https://nordvec.com/it/docs/guides/troubleshooting Soluzioni per gli errori di sincronizzazione e i limiti del piano che puoi incontrare, ognuna partendo dal messaggio che vedi. Ogni pagina parte dal messaggio che Nordvec ti mostra, spiega perché appare e ti guida attraverso la soluzione. Per gli errori restituiti da una richiesta API, consulta [Errori e limiti di frequenza](/docs/guides/errors-and-rate-limits). - [Ricollega un connettore](https://nordvec.com/it/docs/guides/troubleshooting/reconnect-integration): Risolvi gli errori di sincronizzazione "l'autenticazione è scaduta" e "l'accesso è stato revocato" ricollegando il connettore interessato. - [Concedi le autorizzazioni mancanti](https://nordvec.com/it/docs/guides/troubleshooting/insufficient-scopes): Risolvi gli errori di sincronizzazione "autorizzazioni richieste mancanti" ricollegando il connettore e approvando ogni autorizzazione richiesta. - [Limite documenti raggiunto](https://nordvec.com/it/docs/guides/troubleshooting/document-limit): Cosa succede quando il limite documenti del tuo piano mette in pausa la sincronizzazione e come liberare spazio o effettuare l'upgrade per riprenderla. - [Limite di elaborazione giornaliera raggiunto](https://nordvec.com/it/docs/guides/troubleshooting/daily-processing-limit): Cosa succede quando il limite di elaborazione giornaliero della tua area di lavoro mette in pausa la sincronizzazione e quando riprende. --- # Ricollega un connettore Source: https://nordvec.com/it/docs/guides/troubleshooting/reconnect-integration Risolvi gli errori di sincronizzazione "l'autenticazione è scaduta" e "l'accesso è stato revocato" ricollegando il connettore interessato. Quando una sincronizzazione segnala **"La tua autenticazione è scaduta"** o **"Il tuo accesso è stato revocato"**, Nordvec non può più agire per tuo conto presso il provider. La connessione stessa deve essere rinnovata; riprovare la sincronizzazione senza riconnettere non risolve il problema. ## Perché succede [#perché-succede] * Il provider ha fatto scadere la credenziale a lunga durata che Nordvec detiene. Alcuni provider lo fanno secondo una pianificazione fissa, altri dopo un periodo di inattività. * Hai cambiato la password presso il provider, il che comunemente revoca l'accesso a tutte le app connesse. * Tu (o un amministratore dell'area di lavoro) hai revocato l'accesso di Nordvec dalle impostazioni di sicurezza o delle app connesse del provider. * Il provider ha modificato la sua politica di sicurezza (ad esempio dopo attività sospette sul tuo account) e invalidato le autorizzazioni esistenti. ## Come risolvere [#come-risolvere] 1. Apri **Connectors** in Nordvec. 2. Trova il connettore interessato. Mostra lo stato di errore riportato dall'ultima sincronizzazione e un pulsante **Riconnetti** sulla sua scheda. 3. Scegli **Riconnetti** e accedi al provider con lo **stesso account** che hai usato originariamente. Approva ogni permesso elencato dal provider; rifiutarne uno porta a un [errore di permessi mancanti](/docs/guides/troubleshooting/insufficient-scopes) invece. La riconnessione è disponibile anche dai dettagli del connettore in qualsiasi momento, non solo dopo un errore. Riconnettere mantiene tutto ciò che è già stato sincronizzato. Non usare **Disconnetti** per risolvere un accesso scaduto: disconnettere elimina definitivamente ogni documento che il connettore ha sincronizzato. Se accedi con un account diverso da quello con cui il connettore è stato configurato, Nordvec rifiuta la riconnessione e non apporta modifiche. Per cambiare account, disconnetti il connettore e connetti l'altro account. ### Connettori che non possono essere riconnessi in loco [#connettori-che-non-possono-essere-riconnessi-in-loco] Guru, Notion, Zendesk, Freshdesk, Trello ed e-conomic non offrono **Riconnetti**, perché Nordvec non può confermare che un nuovo accesso appartenga allo stesso account. Per questi, disconnetti il connettore e connettilo nuovamente. La disconnessione elimina i documenti sincronizzati e la successiva sincronizzazione li importa di nuovo dall'inizio. ## Cosa succede dopo la riconnessione [#cosa-succede-dopo-la-riconnessione] Il nuovo accesso sostituisce il vecchio e l'errore viene cancellato. Una sincronizzazione parte subito e i documenti che hanno fallito mentre la connessione era inattiva vengono riprovati; gli elementi elencati sotto **"Elementi che non sono stati importati"** scompaiono man mano che vengono importati con successo. I connettori sono connessi per utente: riconnettere rinnova *la tua* connessione e non influisce su quella di nessun altro. Solo la persona che ha collegato un connettore può riconnetterlo, e questo include gli amministratori dell'area di lavoro: un amministratore non può riconnettere il connettore di un collega. --- # Concedi le autorizzazioni mancanti Source: https://nordvec.com/it/docs/guides/troubleshooting/insufficient-scopes Risolvi gli errori di sincronizzazione "autorizzazioni richieste mancanti" ricollegando il connettore e approvando ogni autorizzazione richiesta. Quando una sincronizzazione segnala **"Il tuo account non dispone delle autorizzazioni richieste"**, la connessione al provider funziona, ma sono state concesse meno autorizzazioni (ambiti OAuth) di quelle necessarie al connettore per leggere i tuoi contenuti. Questa è una proprietà dell'autorizzazione stessa, quindi l'unica soluzione è rifare la connessione con il set completo di permessi. ## Perché succede [#perché-succede] * Un permesso è stato rifiutato durante il flusso di connessione originale. Alcuni provider permettono di deselezionare singole autorizzazioni nella schermata di consenso. * Il connettore ha acquisito una funzionalità che richiede un'autorizzazione aggiuntiva, e la tua autorizzazione precedente è antecedente a questa modifica. * Un amministratore dell'area di lavoro ha limitato quali permessi possono essere detenuti da app di terze parti, oppure il provider richiede l'approvazione di un amministratore per alcuni di essi. ## Come risolvere [#come-risolvere] 1. Apri **Connectors** in Nordvec. 2. Trova il connettore interessato e seleziona **Riconnetti** sulla sua scheda. 3. Accedi con lo stesso account che hai usato originariamente e, nella schermata di consenso del provider, approva **tutte** le autorizzazioni richieste. Ognuna di esse corrisponde a una necessità concreta, tipicamente la lettura dei documenti, file o messaggi che il connettore sincronizza; non ci sono extra opzionali nell'elenco. La riconnessione mantiene i documenti già sincronizzati. Guru, Notion, Zendesk, Freshdesk, Trello e e-conomic non possono essere riconnessi direttamente; per questi, scollega e collega nuovamente, operazione che elimina i documenti sincronizzati e li importa di nuovo dall'inizio. Se la schermata di consenso indica che un amministratore deve approvare l'app, inoltra la richiesta al tuo amministratore dell'area di lavoro. I provider con flussi di consenso da amministratore (ad esempio organizzazioni Google Workspace e Microsoft 365, o aree di lavoro Slack con approvazione delle app) bloccano l'autorizzazione finché un amministratore non la concede, e riconnettere prima di tale approvazione produrrà lo stesso errore. ## Cosa succede dopo la riconnessione [#cosa-succede-dopo-la-riconnessione] La nuova autorizzazione sostituisce quella vecchia, l'errore scompare e una sincronizzazione parte immediatamente. Gli elementi che in precedenza avevano fallito a causa di errori di permesso vengono ritentati. --- # Limite documenti raggiunto Source: https://nordvec.com/it/docs/guides/troubleshooting/document-limit Cosa succede quando il limite documenti del tuo piano mette in pausa la sincronizzazione e come liberare spazio o effettuare l'upgrade per riprenderla. Quando una sincronizzazione segnala **"Hai raggiunto il limite di documenti del tuo piano"**, la connessione è integra e non si è verificato alcun errore da parte del provider. Il tuo corpus ha semplicemente raggiunto il numero massimo di documenti consentiti dal piano, quindi l'importazione è stata messa in pausa invece di scartare i contenuti in modo silenzioso. ## Cosa include il limite [#cosa-include-il-limite] Il limite conta i documenti memorizzati nel tuo corpus da tutte le fonti: sincronizzazioni dei connettori, caricamenti e documenti inviati tramite l'API. Esiste per mantenere prevedibili i costi di indicizzazione e ricerca; è una quota per area di lavoro, non per singolo connettore. ## Come riprendere la sincronizzazione [#come-riprendere-la-sincronizzazione] Fai una delle seguenti azioni: * **Libera spazio.** Elimina i documenti che non ti servono più o scollega una fonte i cui contenuti non desideri indicizzare. L'eliminazione di un documento lo rimuove dall'indice immediatamente. * **Aggiorna il piano o aggiungi posti.** La quota è impostata per posto, e i piani superiori consentono più documenti per posto. Non è necessario riavviare manualmente: la successiva sincronizzazione programmata rileva la capacità liberata e riprende dal punto in cui si era interrotta. Puoi anche avviare una sincronizzazione manualmente dalla scheda del connettore una volta che lo spazio è disponibile. ## Cosa succede ai documenti che non sono entrati [#cosa-succede-ai-documenti-che-non-sono-entrati] Niente va perso alla fonte; il provider rimane il sistema di riferimento. I documenti che non sono stati importati vengono recuperati dalla successiva sincronizzazione riuscita, una volta che la capacità lo consente. --- # Limite di elaborazione giornaliera raggiunto Source: https://nordvec.com/it/docs/guides/troubleshooting/daily-processing-limit Cosa succede quando il limite di elaborazione giornaliero della tua area di lavoro mette in pausa la sincronizzazione e quando riprende. Quando una sincronizzazione riporta **"La tua area di lavoro ha raggiunto il limite di elaborazione giornaliero"**, la connessione è attiva e non si è verificato alcun errore da parte del provider. La tua area di lavoro ha elaborato nella giornata la quantità massima di nuovi contenuti consentita dal limite, quindi l'importazione è stata messa in pausa anziché continuare a rifiutare gli elementi uno per uno. ## Cosa copre il limite [#cosa-copre-il-limite] Il limite conteggia il contenuto elaborato per l'indicizzazione da tutte le fonti (sincronizzazioni dei connettori, caricamenti, documenti inviati tramite l'API) in un giorno solare, misurato in UTC. Esiste per evitare che la prima sincronizzazione di una fonte di grandi dimensioni venga eseguita senza limiti in un solo giorno; i contenuti invariati non vengono mai conteggiati nuovamente, quindi dopo l'importazione iniziale un'area di lavoro raramente si avvicina al limite. Il limite è una quota per area di lavoro che scala con il numero di posti, e ogni membro può utilizzare una parte di essa al giorno, quindi l'importazione di grandi dimensioni da parte di una singola persona non può esaurire l'intera quota dell'area di lavoro. ## Come riprende la sincronizzazione [#come-riprende-la-sincronizzazione] Non devi fare nulla. Il connettore è programmato per eseguirsi nuovamente dopo la mezzanotte UTC, quando la quota giornaliera si azzera, e riprende da dove si era interrotto. Il messaggio di stato si cancella durante questa esecuzione. Puoi anche avviare manualmente una sincronizzazione dalla scheda del connettore; riprenderà da dove si era interrotta la precedente, una volta che la quota sarà nuovamente disponibile. ## Cosa succede al contenuto non elaborato [#cosa-succede-al-contenuto-non-elaborato] Nessun dato viene perso alla fonte; il provider rimane il sistema di riferimento. Gli elementi che non sono stati elaborati oggi verranno recuperati dalla prossima esecuzione.