# Context pack: Vianmääritys Source: https://nordvec.com/fi/docs/guides/troubleshooting Pack: https://nordvec.com/fi/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. [Virheet ja rajojen ylitykset](https://nordvec.com/fi/docs/guides/errors-and-rate-limits) (builds on) 2. [Vianmääritys](https://nordvec.com/fi/docs/guides/troubleshooting) (this guide) 3. [Yhdistä liittimet uudelleen](https://nordvec.com/fi/docs/guides/troubleshooting/reconnect-integration) (linked from this guide) 4. [Myönnä puuttuvat käyttöoikeudet](https://nordvec.com/fi/docs/guides/troubleshooting/insufficient-scopes) (linked from this guide) 5. [Asiakirjojen raja saavutettu](https://nordvec.com/fi/docs/guides/troubleshooting/document-limit) (linked from this guide) 6. [Päivittäinen käsittelyraja saavutettu](https://nordvec.com/fi/docs/guides/troubleshooting/daily-processing-limit) (linked from this guide) --- # Virheet ja rajojen ylitykset Source: https://nordvec.com/fi/docs/guides/errors-and-rate-limits Yksi virhekuori, jonka jokainen epäonnistunut pyyntö palauttaa, rajojen ylitystiedot otsikoissa ja kuinka kirjoitus voidaan yrittää uudelleen turvallisesti. Jokainen päätepiste epäonnistuu samalla tavalla, joten asiakas käsittelee virheet, rajoitukset ja uusintayritykset kerran ja käyttää samaa koodia kaikkialla, myös [MCP:n](/docs/guides/mcp) yli. ## Virhekuori [#virhekuori] Jokainen ei-2xx-vastaus on yksi JSON-objekti: ```json { "defined": false, "code": "TOO_MANY_REQUESTS", "message": "Too many requests", "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 } } ``` * `code` on HTTP-tason virhe, esimerkiksi `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BAD_REQUEST` tai `TOO_MANY_REQUESTS`. * `data.reason`, kun se on olemassa, on tarkempi koneellisesti luettava syy, kuten `auth.key_not_found` tai `rate_limit.exceeded`. Haaraa sen perusteella eikä `message`:n perusteella, joka on tarkoitettu ihmisille ja voi muuttua. * `defined` on `true`, kun toiminto luettelee kyseisen virheen [API-viitteessä](/docs/api), ja `false` virheille, joita mikä tahansa pyyntö voi kohdata (todennus, rajoitukset, tuntematon reitti). * Validointivirhe vastaa `BAD_REQUEST`:llä, ja ongelmat ovat `data.formErrors`:ssä ja `data.fieldErrors`:ssä. Jokainen vastaus sisältää myös `X-Request-ID`:n. Mainitse se, kun otat yhteyttä tukeen, niin löydämme kyseisen pyynnön tarkasti. ## Yleiset tilakoodit [#yleiset-tilakoodit] | Tilakoodi | Koodi | Toimenpide | | --------- | ----------------------- | --------------------------------------------------------------------- | | `400` | `BAD_REQUEST` | Korjaa pyyntö; `data.fieldErrors` nimeää kentät | | `401` | `UNAUTHORIZED` | Lähetä kelvollinen avain tai istunto | | `403` | `FORBIDDEN` | Avaimella ei ole vaadittua käyttöoikeutta tai roolia toimintoa varten | | `404` | `NOT_FOUND` | Resurssia ei ole olemassa, tai sinulla ei ole oikeutta nähdä sitä | | `409` | `CONFLICT` | Kaksoiskirjoitus on vielä kesken; yritä uudelleen pian | | `413` | `PAYLOAD_TOO_LARGE` | Pyynnön runko on yli 1 Mt; jaa massapush pienempiin eriin | | `429` | `TOO_MANY_REQUESTS` | Odota `Retry-After`, sitten yritä uudelleen | | `422` | `UNPROCESSABLE_CONTENT` | Pyyntö on hyvin muodostettu, mutta sitä ei voida soveltaa | ## Rajoitukset [#rajoitukset] Jokainen vastaus ilmoittaa rajoituksen, jota vastaan se laskettiin, kahdessa muodossa: * `X-RateLimit-*`-otsikot; * IETF:n strukturoidut kentät `RateLimit` (reaaliaikainen tila: `r` on jäljellä olevat pyynnöt, `t` sekuntia ikkunan nollaukseen) ja `RateLimit-Policy` (kiintiö: `q` on rajoitus, `w` ikkuna sekunteina). `429` sisältää myös `Retry-After` sekunteina ja `data.retryAfterMs`. Odota vähintään niin kauan ennen seuraavaa pyyntöä; aiempi uusintayritys lasketaan ja evätään uudelleen. ## Kirjoitusten turvallinen uusinta [#kirjoitusten-turvallinen-uusinta] Kirjoitustoiminto, joka luettelee `Idempotency-Key`-otsikon [API-viitteessä](/docs/api), voidaan uusia ilman, että työ tehdään kahdesti. Lähetä yksi avain loogista kirjoitusta kohden ja toista sama avain jokaisella uusintakerralla: * sama avain samalla rungolla 24 tunnin sisällä toistaa tallennetun vastauksen; * sama avain eri rungolla evätään `422`:llä; * kaksoiskappale, joka saapuu, kun ensimmäinen on vielä käynnissä, saa `409`:n. Toimintoa, jolla ei ole otsikkoa, ei ole idempotentti, joten yritä sitä uudelleen vain, kun tiedät, että ensimmäinen yritys ei onnistunut. --- # Vianmääritys Source: https://nordvec.com/fi/docs/guides/troubleshooting Korjauksia synkronointivirheisiin ja suunnitelman rajoituksiin, joihin voit törmätä, kukin alkaen näkemästäsi viestistä. Jokainen sivu alkaa Nordvecin näyttämästä viestistä, selittää miksi se tulee näkyviin ja opastaa korjauksen läpi. Jos kyse on API-pyynnön palauttamasta virheestä, katso [Virheet ja rajoitukset](/docs/guides/errors-and-rate-limits). - [Yhdistä liittimet uudelleen](https://nordvec.com/fi/docs/guides/troubleshooting/reconnect-integration): Korjaa synkronointivirheet "todennus on vanhentunut" ja "käyttöoikeus on peruutettu" yhdistämällä kyseinen liitin uudelleen. - [Myönnä puuttuvat käyttöoikeudet](https://nordvec.com/fi/docs/guides/troubleshooting/insufficient-scopes): Korjaa "vaaditut käyttöoikeudet puuttuvat" -synkronointivirheet yhdistämällä liitin uudelleen ja hyväksymällä kaikki pyydetyt käyttöoikeudet. - [Asiakirjojen raja saavutettu](https://nordvec.com/fi/docs/guides/troubleshooting/document-limit): Mitä tapahtuu, kun sinun suunnitelmasi asiakirjaraja keskeyttää synkronoinnin, ja miten voit vapauttaa tilaa tai päivittää jatkaaksesi. - [Päivittäinen käsittelyraja saavutettu](https://nordvec.com/fi/docs/guides/troubleshooting/daily-processing-limit): Mitä tapahtuu, kun työtilasi päivittäinen käsittelyraja keskeyttää synkronoinnin, ja milloin se jatkuu --- # Yhdistä liittimet uudelleen Source: https://nordvec.com/fi/docs/guides/troubleshooting/reconnect-integration Korjaa synkronointivirheet "todennus on vanhentunut" ja "käyttöoikeus on peruutettu" yhdistämällä kyseinen liitin uudelleen. Kun synkronointi ilmoittaa **"Todennuksesi on vanhentunut"** tai **"Pääsysi on peruttu"**, Nordvec ei voi enää toimia puolestasi palveluntarjoajalla. Yhteys on uusittava; synkronoinnin uusintayritys ilman uudelleenyhteyttämistä ei auta. ## Miksi näin tapahtuu [#miksi-näin-tapahtuu] * Palveluntarjoaja on vanhentanut Nordvecin hallussa olevan pitkäikäisen tunnisteen. Jotkut palveluntarjoajat tekevät tämän kiinteän aikataulun mukaan, toiset käyttämättömyyden jälkeen. * Olet vaihtanut salasanasi palveluntarjoajalla, mikä yleensä peruu kaikkien yhdistettyjen sovellusten pääsyn. * Sinä (tai työtilan ylläpitäjä) olet perunut Nordvecin pääsyn palveluntarjoajan yhdistettyjen sovellusten tai tietoturva-asetusten kautta. * Palveluntarjoaja on päivittänyt tietoturvakäytäntönsä (esimerkiksi epäilyttävän toiminnan jälkeen tililläsi) ja mitätöinyt olemassa olevat käyttöoikeudet. ## Miten korjata ongelma [#miten-korjata-ongelma] 1. Avaa **Liittimet** Nordvecissa. 2. Etsi ongelmallinen liitin. Se näyttää viimeisimmän synkronoinnin ilmoittaman virhetilan ja **Yhdistä uudelleen** -painikkeen kortissaan. 3. Valitse **Yhdistä uudelleen** ja kirjaudu palveluntarjoajalle **samalla tilillä**, jolla liitin alun perin yhdistettiin. Hyväksy kaikki palveluntarjoajan luettelemat käyttöoikeudet; yhdenkin epääminen johtaa [puuttuvien käyttöoikeuksien virheeseen](/docs/guides/troubleshooting/insufficient-scopes). Yhdistäminen uudelleen onnistuu myös liittimen tiedoista milloin tahansa, ei vain virheen jälkeen. Uudelleenyhteyttäminen säilyttää kaiken jo synkronoidun. Älä käytä **Katkaise yhteys** -toimintoa vanhentuneen kirjautumisen korjaamiseen: yhteyden katkaiseminen poistaa pysyvästi kaikki liittimen synkronoimat asiakirjat. Jos kirjaudut eri tilillä kuin se, jolla liitin alun perin asetettiin, Nordvec hylkää uudelleenyhteyden eikä muuta mitään. Vaihtaaksesi tiliä, katkaise liittimen yhteys ja yhdistä toinen tili sen sijaan. ### Liittimet, joita ei voi yhdistää uudelleen paikan päällä [#liittimet-joita-ei-voi-yhdistää-uudelleen-paikan-päällä] Guru, Notion, Zendesk, Freshdesk, Trello ja e-conomic eivät tarjoa **Yhdistä uudelleen** -toimintoa, koska Nordvec ei voi vahvistaa, kuuluuko uusi kirjautuminen samalle tilille. Näissä tapauksissa katkaise liittimen yhteys ja yhdistä se uudelleen. Yhteyden katkaiseminen poistaa synkronoidut asiakirjat, ja seuraava synkronointi tuo ne uudelleen alusta alkaen. ## Mitä tapahtuu uudelleenyhteyden jälkeen [#mitä-tapahtuu-uudelleenyhteyden-jälkeen] Uusi kirjautuminen korvaa vanhan, ja virhe poistuu. Synkronointi alkaa heti, ja asiakirjat, jotka epäonnistuivat yhteyden ollessa poikki, yritetään uudelleen. Kohteet, jotka on lueteltu otsikon **"Tuontiin kelpaamattomat kohteet"** alla, poistuvat listalta, kun ne tuodaan onnistuneesti. Liittimet on yhdistetty käyttäjäkohtaisesti: uudelleenyhteyttäminen uusii *sinun* yhteytesi eikä vaikuta muiden yhteyksiin. Vain henkilö, joka on yhdistänyt liittimen, voi yhdistää sen uudelleen, ja tähän kuuluvat myös työtilan ylläpitäjät: ylläpitäjä ei voi yhdistää uudelleen kollegan liitintä. --- # Myönnä puuttuvat käyttöoikeudet Source: https://nordvec.com/fi/docs/guides/troubleshooting/insufficient-scopes Korjaa "vaaditut käyttöoikeudet puuttuvat" -synkronointivirheet yhdistämällä liitin uudelleen ja hyväksymällä kaikki pyydetyt käyttöoikeudet. Kun synkronointi raportoi virheen **"Tililtäsi puuttuu vaadittuja oikeuksia"**, yhteys palveluntarjoajaan toimii, mutta sille on myönnetty vähemmän oikeuksia (OAuth-scopet) kuin liittimellä tarvitaan sisältösi lukemiseen. Tämä on myöntämisen ominaisuus, joten ainoa korjaus on muodostaa yhteys uudelleen täydellä oikeusjoukolla. ## Miksi näin tapahtuu [#miksi-näin-tapahtuu] * Oikeus evättiin alkuperäisen yhteydenmuodostuksen aikana. Jotkin palveluntarjoajat antavat poistaa yksittäisiä oikeuksia suostumusnäytöltä valinnan. * Liittimeen on lisätty ominaisuus, joka vaatii uuden oikeuden, ja vanhempi myöntämäsi oikeus on sitä vanhempi. * Työtilan ylläpitäjä on rajoittanut, mitä oikeuksia kolmannen osapuolen sovellukset voivat pitää hallussaan, tai palveluntarjoaja vaatii ylläpitäjän hyväksynnän joillekin oikeuksista. ## Miten korjaat [#miten-korjaat] 1. Avaa **Liittimet** Nordvecissa. 2. Etsi kyseinen liitin ja valitse sen kortista **Yhdistä uudelleen**. 3. Kirjaudu sisään samalla tilillä, jolla alun perin yhdistit, ja hyväksy palveluntarjoajan suostumusnäytöllä **kaikki** pyydetyt oikeudet. Jokainen oikeus vastaa konkreettista tarvetta, tyypillisesti synkronoitavien dokumenttien, tiedostojen tai viestien lukemista; listassa ei ole valinnaisia lisäoikeuksia. Yhteyden uudelleenmuodostaminen säilyttää jo synkronoidut dokumentit. Guru, Notion, Zendesk, Freshdesk, Trello ja e-conomic eivät tue yhteyden uudelleenmuodostamista paikan päällä. Näissä tapauksissa katkaise yhteys ja muodosta se uudelleen, mikä poistaa synkronoidut dokumentit ja tuo ne uudelleen alusta alkaen. Jos suostumusnäyttö ilmoittaa, että sovelluksen on hyväksyttävä työtilan ylläpitäjä, välitä pyyntö työtilasi ylläpitäjälle. Palveluntarjoajat, joissa on ylläpitäjän hyväksyntäprosessi (esimerkiksi Google Workspace- ja Microsoft 365-organisaatiot tai Slack-työtilat, joissa sovellusten hyväksyntä on käytössä), estävät oikeuksien myöntämisen, kunnes ylläpitäjä hyväksyy sen. Yhteyden uudelleenmuodostaminen ennen hyväksyntää aiheuttaa saman virheen. ## Mitä tapahtuu yhteyden uudelleenmuodostamisen jälkeen [#mitä-tapahtuu-yhteyden-uudelleenmuodostamisen-jälkeen] Uusi oikeuksien myöntäminen korvaa vanhan, virhe poistuu ja synkronointi alkaa heti. Aiemmin oikeusvirheiden takia epäonnistuneet kohteet yritetään uudelleen. --- # Asiakirjojen raja saavutettu Source: https://nordvec.com/fi/docs/guides/troubleshooting/document-limit Mitä tapahtuu, kun sinun suunnitelmasi asiakirjaraja keskeyttää synkronoinnin, ja miten voit vapauttaa tilaa tai päivittää jatkaaksesi. Kun synkronointi ilmoittaa **"Olet saavuttanut tilauksesi dokumenttirajan"**, yhteys on kunnossa eikä palveluntarjoajalla tapahtunut virheitä. Korpuksesi on yksinkertaisesti saavuttanut maksimi dokumenttimäärän, jonka tilauksesi sallii, joten tuonti keskeytettiin hiljaisen sisällön pudottamisen sijaan. ## Mitä raja kattaa [#mitä-raja-kattaa] Raja laskee korpukseesi tallennettujen dokumenttien määrän kaikista lähteistä: liittimien synkronoinnit, lataukset ja API:n kautta työnnetyt dokumentit. Se on olemassa, jotta indeksointi- ja hakukustannukset pysyvät ennakoitavina. Raja on työtilakohtainen, ei liittimen mukainen. ## Synkronoinnin jatkaminen [#synkronoinnin-jatkaminen] Tee jompikumpi seuraavista: * **Vapauta tilaa.** Poista dokumentteja, joita et enää tarvitse, tai irrota lähde, jonka sisältöä et halua indeksoida. Dokumentin poistaminen poistaa sen indeksistä välittömästi. * **Päivitä tilauksesi tai lisää käyttäjiä.** Raja on määritetty käyttäjää kohden, ja korkeammat tilaukset sallivat enemmän dokumentteja käyttäjää kohden. Manuaalista käynnistystä ei tarvita jälkeenpäin: seuraava aikataulutettu synkronointi havaitsee vapautuneen tilan ja jatkaa siitä, mihin jäi. Voit myös käynnistää synkronoinnin manuaalisesti liittimen kortilta, kun tilaa on saatavilla. ## Mitä tapahtuu dokumenteille, jotka eivät mahtuneet [#mitä-tapahtuu-dokumenteille-jotka-eivät-mahtuneet] Mikään ei häviä lähteestä; palveluntarjoaja säilyy tietojen pääjärjestelmänä. Dokumentit, joita ei voitu tuoda, poimitaan seuraavassa onnistuneessa synkronoinnissa, kun kapasiteettia on jälleen käytettävissä. --- # Päivittäinen käsittelyraja saavutettu Source: https://nordvec.com/fi/docs/guides/troubleshooting/daily-processing-limit Mitä tapahtuu, kun työtilasi päivittäinen käsittelyraja keskeyttää synkronoinnin, ja milloin se jatkuu Kun synkronointi ilmoittaa **"Työtilasi saavutti tämän päivän käsittelyrajan"**, yhteys on kunnossa eikä palveluntarjoajalla tapahtunut virheitä. Työtilasi on käsitellyt niin paljon uutta sisältöä yhden päivän aikana kuin sen raja sallii, joten tuonti keskeytettiin sen sijaan, että yksittäisiä kohteita hylättäisiin. ## Mitä raja kattaa [#mitä-raja-kattaa] Raja laskee kaiken indeksointia varten käsitellyn sisällön määrän kaikista lähteistä (liittimien synkronoinneista, latauksista, API:n kautta lähetetyistä dokumenteista) yhden kalenteripäivän aikana, mitattuna UTC-aikavyöhykkeellä. Raja on olemassa, jotta suuren lähteen ensimmäinen synkronointi ei jatkuisi rajattomasti yhden päivän aikana. Muuttumattoman sisällön määrä ei koskaan lasketa uudelleen, joten työtila harvoin lähestyy rajaa alkuperäisen tuonnin jälkeen. Raja on työtilakohtainen kiintiö, joka skaalautuu käyttäjämäärän mukaan, ja jokainen jäsen voi käyttää osansa siitä päivässä. Näin yhden henkilön suuri tuonti ei voi kuluttaa koko työtilan kiintiötä. ## Miten synkronointi jatkuu [#miten-synkronointi-jatkuu] Sinun ei tarvitse tehdä mitään. Liitin on ajoitettu suoritettavaksi uudelleen keskiyön jälkeen UTC-aikaa, jolloin päivän kiintiö nollautuu, ja se jatkaa siitä, mihin jäi. Tilaviesti poistuu seuraavalla suorituskerralla. Voit myös käynnistää synkronoinnin manuaalisesti liittimen kortista. Se jatkaa siitä, mihin edellinen jäi, kun kiintiö on jälleen käytettävissä. ## Mitä tapahtuu käsittelemättä jääneelle sisällölle [#mitä-tapahtuu-käsittelemättä-jääneelle-sisällölle] Mikään ei häviä lähteestä, sillä palveluntarjoaja säilyy tietojen pääjärjestelmänä. Kohteet, joita ei ehditty käsitellä tänään, poimitaan seuraavalla suorituskerralla.