# Context pack: Fehlerbehebung Source: https://nordvec.com/de/docs/guides/troubleshooting Pack: https://nordvec.com/de/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. [Fehler und Ratenbegrenzungen](https://nordvec.com/de/docs/guides/errors-and-rate-limits) (builds on) 2. [Fehlerbehebung](https://nordvec.com/de/docs/guides/troubleshooting) (this guide) 3. [Einen Connector neu verbinden](https://nordvec.com/de/docs/guides/troubleshooting/reconnect-integration) (linked from this guide) 4. [Fehlende Berechtigungen erteilen](https://nordvec.com/de/docs/guides/troubleshooting/insufficient-scopes) (linked from this guide) 5. [Dokumentenlimit erreicht](https://nordvec.com/de/docs/guides/troubleshooting/document-limit) (linked from this guide) 6. [Tagesverarbeitungslimit erreicht](https://nordvec.com/de/docs/guides/troubleshooting/daily-processing-limit) (linked from this guide) --- # Fehler und Ratenbegrenzungen Source: https://nordvec.com/de/docs/guides/errors-and-rate-limits Die eine Fehlerhülle, die jede fehlgeschlagene Anfrage zurückgibt, die Ratenbegrenzungs-Header und wie du einen Schreibvorgang sicher wiederholst. Jeder Endpunkt schlägt auf die gleiche Weise fehl, daher behandelst du Fehler, Ratenlimits und Wiederholungsversuche einmal und verwendest diesen Code überall wieder, auch über [MCP](/docs/guides/mcp). ## Die Fehlerhülle [#die-fehlerhülle] Jede nicht-2xx-Antwort ist ein JSON-Objekt: ```json { "defined": false, "code": "TOO_MANY_REQUESTS", "message": "Too many requests", "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 } } ``` * `code` ist der HTTP-Level-Fehler, zum Beispiel `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BAD_REQUEST` oder `TOO_MANY_REQUESTS`. * `data.reason` ist, falls vorhanden, ein genauerer maschinenlesbarer Grund wie `auth.key_not_found` oder `rate_limit.exceeded`. Verzweige darauf statt auf `message`, das für Menschen gedacht ist und sich ändern kann. * `defined` ist `true`, wenn die Operation diesen Fehler in der [API-Referenz](/docs/api) auflistet, und `false` für Fehler, die jede Anfrage treffen können (Authentifizierung, Ratenlimits, eine unbekannte Route). * Eine Validierungsfehlermeldung antwortet mit `BAD_REQUEST` und den Problemen in `data.formErrors` und `data.fieldErrors`. Jede Antwort enthält außerdem eine `X-Request-ID`. Gib sie an, wenn du den Support kontaktierst, damit wir diese genaue Anfrage finden können. ## Häufige Statuscodes [#häufige-statuscodes] | Status | Code | Was zu tun ist | | ------ | ----------------------- | ---------------------------------------------------------------------------------------- | | `400` | `BAD_REQUEST` | Korrigiere die Anfrage; `data.fieldErrors` benennt die Felder | | `401` | `UNAUTHORIZED` | Sende einen gültigen Schlüssel oder eine gültige Session | | `403` | `FORBIDDEN` | Der Schlüssel hat nicht den benötigten Scope oder die benötigte Rolle für die Operation | | `404` | `NOT_FOUND` | Die Ressource existiert nicht oder du darfst sie nicht sehen | | `409` | `CONFLICT` | Ein doppelter Schreibvorgang ist noch in Bearbeitung; wiederhole den Versuch kurzfristig | | `413` | `PAYLOAD_TOO_LARGE` | Der Anfragekörper ist über 1 MB groß; teile einen Massen-Push in kleinere Chargen auf | | `422` | `UNPROCESSABLE_CONTENT` | Die Anfrage ist korrekt formuliert, kann aber nicht angewendet werden | | `429` | `TOO_MANY_REQUESTS` | Warte `Retry-After`, dann wiederhole den Versuch | ## Ratenlimits [#ratenlimits] Jede Antwort gibt das Limit an, gegen das sie gezählt wurde, in zwei Formen: * die `X-RateLimit-*`-Header; * die IETF-Strukturfelder `RateLimit` (Live-Zustand: `r` sind die verbleibenden Anfragen, `t` die Sekunden bis zum Zurücksetzen des Fensters) und `RateLimit-Policy` (das Kontingent: `q` ist das Limit, `w` das Fenster in Sekunden). Eine `429` enthält außerdem `Retry-After` in Sekunden und `data.retryAfterMs`. Warte mindestens so lange, bevor du die nächste Anfrage sendest; ein früherer Wiederholungsversuch wird gezählt und abgelehnt. ## Schreibvorgänge sicher wiederholen [#schreibvorgänge-sicher-wiederholen] Ein Schreibvorgang, der einen `Idempotency-Key`-Header in der [API-Referenz](/docs/api) auflistet, kann wiederholt werden, ohne die Arbeit doppelt auszuführen. Sende einen Schlüssel pro logischem Schreibvorgang und wiederhole denselben Schlüssel bei jedem Wiederholungsversuch: * derselbe Schlüssel mit demselben Body innerhalb von 24 Stunden gibt die gespeicherte Antwort erneut aus; * derselbe Schlüssel mit einem anderen Body wird mit `422` abgelehnt; * ein Duplikat, das ankommt, während der erste Vorgang noch läuft, erhält `409`. Ein Vorgang ohne diesen Header ist nicht idempotent, daher wiederhole ihn nur, wenn du sicher bist, dass der erste Versuch nicht erfolgreich war. --- # Fehlerbehebung Source: https://nordvec.com/de/docs/guides/troubleshooting Lösungen für die Synchronisationsfehler und Planlimits, auf die du stoßen kannst, jeweils beginnend mit der Meldung, die du siehst. Jede Seite beginnt mit der Meldung, die Nordvec dir anzeigt, erklärt, warum sie erscheint, und führt dich durch die Lösung. Bei Fehlern, die eine API-Anfrage zurückgibt, siehe [Fehler und Ratenlimits](/docs/guides/errors-and-rate-limits). - [Einen Connector neu verbinden](https://nordvec.com/de/docs/guides/troubleshooting/reconnect-integration): Behebe Sync-Fehler wie "Authentifizierung ist abgelaufen" und "Zugriff wurde widerrufen", indem du den betroffenen Connector neu verbindest. - [Fehlende Berechtigungen erteilen](https://nordvec.com/de/docs/guides/troubleshooting/insufficient-scopes): Behebe Sync-Fehler wegen "fehlender erforderlicher Berechtigungen", indem du den Connector neu verbindest und jede angeforderte Berechtigung bestätigst. - [Dokumentenlimit erreicht](https://nordvec.com/de/docs/guides/troubleshooting/document-limit): Was passiert, wenn das Dokumentenlimit deines Tarifs die Synchronisierung pausiert, und wie du Speicherplatz freigibst oder upgradest, um fortzufahren. - [Tagesverarbeitungslimit erreicht](https://nordvec.com/de/docs/guides/troubleshooting/daily-processing-limit): Was passiert, wenn das tägliche Verarbeitungslimit deines Arbeitsbereichs die Synchronisierung pausiert, und wann sie fortgesetzt wird. --- # Einen Connector neu verbinden Source: https://nordvec.com/de/docs/guides/troubleshooting/reconnect-integration Behebe Sync-Fehler wie "Authentifizierung ist abgelaufen" und "Zugriff wurde widerrufen", indem du den betroffenen Connector neu verbindest. Wenn eine Synchronisierung die Meldung **"Deine Authentifizierung ist abgelaufen"** oder **"Dein Zugriff wurde widerrufen"** anzeigt, kann Nordvec nicht mehr in deinem Namen beim Anbieter agieren. Die Verbindung selbst muss erneuert werden; ein erneuter Synchronisierungsversuch ohne erneute Verbindung hilft nicht. ## Warum das passiert [#warum-das-passiert] * Der Anbieter hat das langlebige Credential, das Nordvec besitzt, abgelaufen. Manche Anbieter tun dies nach einem festen Zeitplan, andere nach einer Phase der Inaktivität. * Du hast dein Passwort beim Anbieter geändert, was normalerweise alle verbundenen Apps widerruft. * Du (oder ein Admin deines Arbeitsbereichs) hast den Zugriff von Nordvec in den verbundenen Apps oder Sicherheitseinstellungen des Anbieters widerrufen. * Der Anbieter hat seine Sicherheitsrichtlinien geändert (zum Beispiel nach verdächtigen Aktivitäten auf deinem Konto) und bestehende Berechtigungen für ungültig erklärt. ## So behebst du das Problem [#so-behebst-du-das-problem] 1. Öffne **Connectors** in Nordvec. 2. Suche den betroffenen Connector. Er zeigt den Fehlerstatus der letzten Synchronisierung und einen **Erneut verbinden**-Button auf seiner Karte an. 3. Wähle **Erneut verbinden** und melde dich beim Anbieter mit dem **gleichen Konto** an, mit dem du ursprünglich verbunden hast. Bestätige jede Berechtigung, die der Anbieter auflistet; das Ablehnen einer führt stattdessen zu einem [Fehler wegen fehlender Berechtigungen](/docs/guides/troubleshooting/insufficient-scopes). Die Option **Erneut verbinden** ist auch jederzeit über die Connector-Details verfügbar, nicht nur nach einem Fehler. Durch das erneute Verbinden bleibt alles bereits Synchronisierte erhalten. Verwende **Trennen** nicht, um eine abgelaufene Anmeldung zu beheben: Durch das Trennen werden alle vom Connector synchronisierten Dokumente dauerhaft gelöscht. Wenn du dich mit einem anderen Konto als dem, mit dem der Connector eingerichtet wurde, anmeldest, lehnt Nordvec die erneute Verbindung ab und ändert nichts. Um das Konto zu wechseln, trenne den Connector und verbinde stattdessen das andere Konto. ### Connectors, die nicht direkt erneut verbunden werden können [#connectors-die-nicht-direkt-erneut-verbunden-werden-können] Guru, Notion, Zendesk, Freshdesk, Trello und e-conomic bieten keine Option **Erneut verbinden**, da Nordvec nicht bestätigen kann, dass eine neue Anmeldung zum selben Konto gehört. Für diese trenne den Connector und verbinde ihn erneut. Durch das Trennen werden die synchronisierten Dokumente gelöscht, und die nächste Synchronisierung importiert sie von Anfang an erneut. ## Was nach dem erneuten Verbinden passiert [#was-nach-dem-erneuten-verbinden-passiert] Die neue Anmeldung ersetzt die alte und der Fehler wird behoben. Eine Synchronisierung startet sofort, und Dokumente, die während der Unterbrechung der Verbindung fehlgeschlagen sind, werden erneut versucht. Die unter **"Elemente, die nicht importiert werden konnten"** aufgelisteten Einträge verschwinden, sobald sie erfolgreich importiert wurden. Connectors sind pro Nutzer verbunden: Durch das erneute Verbinden wird *deine* Verbindung erneuert und hat keine Auswirkungen auf die Verbindungen anderer. Nur die Person, die einen Connector verbunden hat, kann ihn erneut verbinden, das gilt auch für Admins eines Arbeitsbereichs: Ein Admin kann den Connector eines Kollegen nicht erneut verbinden. --- # Fehlende Berechtigungen erteilen Source: https://nordvec.com/de/docs/guides/troubleshooting/insufficient-scopes Behebe Sync-Fehler wegen "fehlender erforderlicher Berechtigungen", indem du den Connector neu verbindest und jede angeforderte Berechtigung bestätigst. Wenn eine Synchronisierung die Meldung **"Deinem Konto fehlen erforderliche Berechtigungen"** anzeigt, funktioniert die Verbindung zum Provider, aber es wurden weniger Berechtigungen (OAuth-Bereiche) erteilt, als der Connector benötigt, um deine Inhalte zu lesen. Dies ist eine Eigenschaft der Berechtigung selbst, daher ist die einzige Lösung, die Verbindung mit dem vollständigen Berechtigungssatz neu herzustellen. ## Warum das passiert [#warum-das-passiert] * Eine Berechtigung wurde während des ursprünglichen Verbindungsvorgangs abgelehnt. Einige Provider ermöglichen es dir, einzelne Berechtigungen auf dem Zustimmungsbildschirm abzuwählen. * Der Connector hat eine neue Funktion erhalten, die eine zusätzliche Berechtigung benötigt, und deine ältere Genehmigung stammt aus der Zeit davor. * Ein Arbeitsbereichs-Administrator hat eingeschränkt, welche Berechtigungen Drittanbieter-Apps besitzen dürfen, oder der Provider verlangt eine Administrator-Genehmigung für einige davon. ## So behebst du das Problem [#so-behebst-du-das-problem] 1. Öffne **Connectors** in Nordvec. 2. Suche den betroffenen Connector und wähle **Neu verbinden** auf seiner Karte aus. 3. Melde dich mit demselben Konto an, das du ursprünglich verbunden hast, und genehmige auf dem Zustimmungsbildschirm des Providers **alle** angeforderten Berechtigungen. Jede davon entspricht einem konkreten Bedarf, typischerweise dem Lesen der Dokumente, Dateien oder Nachrichten, die der Connector synchronisiert. Es gibt keine optionalen Extras in der Liste. Durch das Neuverbinden bleiben die bereits synchronisierten Dokumente erhalten. Guru, Notion, Zendesk, Freshdesk, Trello und e-conomic können nicht direkt neu verbunden werden. Für diese trenne die Verbindung und verbinde sie erneut, wodurch die synchronisierten Dokumente gelöscht und von Grund auf neu importiert werden. Falls auf dem Zustimmungsbildschirm steht, dass ein Administrator die App genehmigen muss, leite die Anfrage an deinen Arbeitsbereichs-Administrator weiter. Provider mit Administrator-Zustimmungsprozessen (zum Beispiel Google Workspace- und Microsoft 365-Organisationen oder Slack-Arbeitsbereiche mit App-Genehmigung) blockieren die Genehmigung, bis ein Administrator sie erlaubt. Ein erneutes Verbinden vor dieser Genehmigung führt zum gleichen Fehler. ## Was nach dem Neuverbinden passiert [#was-nach-dem-neuverbinden-passiert] Die neue Berechtigung ersetzt die alte, der Fehler wird behoben und eine Synchronisierung startet sofort. Elemente, die zuvor aufgrund von Berechtigungsfehlern fehlgeschlagen sind, werden erneut versucht. --- # Dokumentenlimit erreicht Source: https://nordvec.com/de/docs/guides/troubleshooting/document-limit Was passiert, wenn das Dokumentenlimit deines Tarifs die Synchronisierung pausiert, und wie du Speicherplatz freigibst oder upgradest, um fortzufahren. Wenn eine Synchronisierung die Meldung **"Du hast das Dokumentenlimit deines Plans erreicht"** anzeigt, ist die Verbindung intakt und beim Provider ist nichts fehlgeschlagen. Dein Korpus hat einfach die maximale Anzahl an Dokumenten erreicht, die dein Plan zulässt. Daher wurde der Import pausiert, anstatt Inhalte stillschweigend zu verwerfen. ## Was das Limit umfasst [#was-das-limit-umfasst] Das Limit zählt Dokumente, die in deinem Korpus über alle Quellen hinweg gespeichert sind: Connector-Synchronisierungen, Uploads und Dokumente, die über die API hochgeladen wurden. Es dient dazu, die Indexierungs- und Suchkosten vorhersehbar zu halten. Es handelt sich um ein Kontingent pro Arbeitsbereich, nicht pro Connector. ## So setzt du die Synchronisierung fort [#so-setzt-du-die-synchronisierung-fort] Führe eine der folgenden Maßnahmen durch: * **Platz freimachen.** Lösche Dokumente, die du nicht mehr benötigst, oder trenne eine Quelle, deren Inhalt du nicht indexieren möchtest. Durch das Löschen eines Dokuments wird es sofort aus dem Index entfernt. * **Deinen Plan upgraden oder Arbeitsplätze hinzufügen.** Das Kontingent wird pro Arbeitsplatz festgelegt, und höhere Pläne erlauben mehr Dokumente pro Arbeitsplatz. Anschließend ist kein manueller Neustart erforderlich: Die nächste geplante Synchronisierung erkennt den freigewordenen Speicherplatz und setzt dort fort, wo sie aufgehört hat. Sobald Speicherplatz verfügbar ist, kannst du auch manuell eine Synchronisierung über die Connector-Karte auslösen. ## Was mit Dokumenten passiert, die nicht importiert werden konnten [#was-mit-dokumenten-passiert-die-nicht-importiert-werden-konnten] Am Quellort geht nichts verloren; der Provider bleibt das führende System. Dokumente, die nicht importiert werden konnten, werden von der nächsten erfolgreichen Synchronisierung übernommen, sobald wieder Kapazität verfügbar ist. --- # Tagesverarbeitungslimit erreicht Source: https://nordvec.com/de/docs/guides/troubleshooting/daily-processing-limit Was passiert, wenn das tägliche Verarbeitungslimit deines Arbeitsbereichs die Synchronisierung pausiert, und wann sie fortgesetzt wird. Wenn eine Synchronisierung die Meldung **„Dein Arbeitsbereich hat das heutige Verarbeitungslimit erreicht“** anzeigt, ist die Verbindung intakt und es ist kein Fehler beim Provider aufgetreten. Dein Arbeitsbereich hat an einem Tag so viel neuen Inhalt verarbeitet, wie das Limit erlaubt. Daher wurde der Import pausiert, statt einzelne Elemente abzulehnen. ## Was das Limit umfasst [#was-das-limit-umfasst] Das Limit zählt den Inhalt, der für die Indizierung über alle Quellen hinweg verarbeitet wird (Connector-Syncs, Uploads, Dokumente, die über die API hochgeladen werden) an einem Kalendertag, gemessen in UTC. Es soll verhindern, dass die erste Synchronisierung einer großen Quelle an einem einzigen Tag unbegrenzt läuft. Unveränderter Inhalt wird nicht erneut gezählt, sodass ein Arbeitsbereich nach dem ersten Import selten an das Limit stößt. Das Limit ist ein pro-Arbeitsbereich-Kontingent, das mit der Anzahl der Plätze skaliert. Jedes Mitglied kann täglich einen Anteil davon nutzen, sodass ein einzelner großer Import nicht das gesamte Kontingent des Arbeitsbereichs aufbraucht. ## Wie die Synchronisierung fortgesetzt wird [#wie-die-synchronisierung-fortgesetzt-wird] Du musst nichts unternehmen. Der Connector ist so geplant, dass er nach Mitternacht UTC erneut ausgeführt wird, wenn das Tageskontingent zurückgesetzt wird, und setzt dort fort, wo er aufgehört hat. Die Statusmeldung wird bei diesem Durchlauf gelöscht. Du kannst auch manuell eine Synchronisierung über die Connector-Karte auslösen. Sobald das Kontingent verfügbar ist, wird dort fortgefahren, wo die vorherige Synchronisierung aufgehört hat. ## Was mit Inhalten passiert, die nicht verarbeitet wurden [#was-mit-inhalten-passiert-die-nicht-verarbeitet-wurden] Nichts geht beim Provider verloren; dieser bleibt das führende System. Die Einträge, die heute nicht verarbeitet werden konnten, werden beim nächsten Durchlauf übernommen.