# Context pack: Rozwiązywanie problemów

Source: https://nordvec.com/pl/docs/guides/troubleshooting
Pack: https://nordvec.com/pl/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. [Błędy i limity zapytań](https://nordvec.com/pl/docs/guides/errors-and-rate-limits) (builds on)
2. [Rozwiązywanie problemów](https://nordvec.com/pl/docs/guides/troubleshooting) (this guide)
3. [Ponownie połącz łącznik](https://nordvec.com/pl/docs/guides/troubleshooting/reconnect-integration) (linked from this guide)
4. [Nadaj brakujące uprawnienia](https://nordvec.com/pl/docs/guides/troubleshooting/insufficient-scopes) (linked from this guide)
5. [Osiągnięto limit dokumentów](https://nordvec.com/pl/docs/guides/troubleshooting/document-limit) (linked from this guide)
6. [Osiągnięto dzienny limit przetwarzania](https://nordvec.com/pl/docs/guides/troubleshooting/daily-processing-limit) (linked from this guide)

---

# Błędy i limity zapytań
Source: https://nordvec.com/pl/docs/guides/errors-and-rate-limits

Jedna struktura błędu zwracana przy każdym nieudanym zapytaniu, nagłówki limitu zapytań oraz jak bezpiecznie ponowić zapis.



Każdy endpoint zwraca błędy w ten sam sposób, więc obsługujesz błędy, limity i ponawianie żądań raz, a następnie używasz tego kodu wszędzie, także przez [MCP](/docs/guides/mcp).

## Struktura odpowiedzi błędu [#struktura-odpowiedzi-błędu]

Każda odpowiedź, która nie jest kodem 2xx, to jeden obiekt JSON:

```json
{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}
```

* `code` to błąd na poziomie HTTP, na przykład `UNAUTHORIZED`, `FORBIDDEN`,
  `NOT_FOUND`, `BAD_REQUEST` lub `TOO_MANY_REQUESTS`.
* `data.reason`, jeśli występuje, to dokładniejszy, zrozumiały dla maszyny powód, taki jak
  `auth.key_not_found` lub `rate_limit.exceeded`. Rozgałęziaj kod na podstawie tego pola, a nie na podstawie
  `message`, które jest przeznaczone dla ludzi i może się zmienić.
* `defined` to `true`, gdy operacja wymienia ten błąd w
  [dokumentacji API](/docs/api), oraz `false` dla błędów, które może napotkać każde żądanie
  (uwierzytelnianie, limity, nieznana ścieżka).
* Nieudana walidacja zwraca `BAD_REQUEST` z problemami w
  `data.formErrors` i `data.fieldErrors`.

Każda odpowiedź zawiera również `X-Request-ID`. Cytuj go, gdy kontaktujesz się z pomocą techniczną,
a my odnajdziemy dokładnie to żądanie.

## Najczęstsze kody statusów [#najczęstsze-kody-statusów]

| Status | Kod                     | Co zrobić                                                                      |
| ------ | ----------------------- | ------------------------------------------------------------------------------ |
| `400`  | `BAD_REQUEST`           | Popraw żądanie; `data.fieldErrors` wskazuje pola                               |
| `401`  | `UNAUTHORIZED`          | Wyślij poprawny klucz lub sesję                                                |
| `403`  | `FORBIDDEN`             | Klucz nie ma wymaganego zakresu lub roli dla tej operacji                      |
| `404`  | `NOT_FOUND`             | Zasób nie istnieje lub nie masz do niego dostępu                               |
| `409`  | `CONFLICT`              | Duplikowane żądanie zapisu jest w trakcie przetwarzania; ponów próbę za chwilę |
| `413`  | `PAYLOAD_TOO_LARGE`     | Ciało żądania przekracza 1 MB; podziel przesyłanie zbiorcze na mniejsze partie |
| `422`  | `UNPROCESSABLE_CONTENT` | Żądanie jest poprawnie sformułowane, ale nie może zostać zastosowane           |
| `429`  | `TOO_MANY_REQUESTS`     | Poczekaj na `Retry-After`, a następnie ponów próbę                             |

## Limity żądań [#limity-żądań]

Każda odpowiedź zawiera informacje o limicie, względem którego zostało zliczone żądanie, w dwóch formach:

* nagłówki `X-RateLimit-*`;
* strukturalne pola IETF `RateLimit` (aktualny stan: `r` to liczba pozostałych żądań,
  `t` to sekundy do resetu okna) oraz `RateLimit-Policy`
  (kwota: `q` to limit, `w` to okno w sekundach).

Odpowiedź `429` zawiera również `Retry-After` w sekundach oraz `data.retryAfterMs`. Poczekaj co najmniej tyle czasu przed następnym żądaniem; ponowienie próby wcześniej zostanie zliczone i odrzucone ponownie.

## Bezpieczne ponawianie żądań zapisu [#bezpieczne-ponawianie-żądań-zapisu]

Operacja zapisu, która wymienia nagłówek `Idempotency-Key` w
[dokumentacji API](/docs/api), może być ponawiana bez ryzyka podwójnego wykonania. Wyślij jeden klucz na logiczną operację zapisu i powtarzaj ten sam klucz przy każdej próbie ponowienia:

* ten sam klucz z tym samym ciałem w ciągu 24 godzin odtwarza zapisaną odpowiedź;
* ten sam klucz z innym ciałem jest odrzucany z kodem `422`;
* duplikat, który dotrze, gdy pierwsze żądanie jest jeszcze w trakcie przetwarzania, otrzymuje `409`.

Operacja bez tego nagłówka nie jest idempotentna, więc ponawiaj ją tylko wtedy, gdy wiesz, że pierwsza próba nie została zrealizowana.


---

# Rozwiązywanie problemów
Source: https://nordvec.com/pl/docs/guides/troubleshooting

Poprawki błędów synchronizacji i limitów planu, na które możesz natrafić, każda zaczynająca się od komunikatu, który widzisz.



Każda strona zaczyna się od komunikatu, który pokazuje ci Nordvec, wyjaśnia, dlaczego się pojawia, i przeprowadza przez rozwiązanie. W przypadku błędów zwracanych przez żądanie API, zobacz [Błędy i limity](/docs/guides/errors-and-rate-limits).

- [Ponownie połącz łącznik](https://nordvec.com/pl/docs/guides/troubleshooting/reconnect-integration): Napraw błędy synchronizacji "uwierzytelnianie wygasło" i "dostęp został cofnięty", ponownie łącząc dotknięty łącznik.
- [Nadaj brakujące uprawnienia](https://nordvec.com/pl/docs/guides/troubleshooting/insufficient-scopes): Napraw błędy synchronizacji "brakujące wymagane uprawnienia", ponownie łącząc łącznik i zatwierdzając każde żądane uprawnienie.
- [Osiągnięto limit dokumentów](https://nordvec.com/pl/docs/guides/troubleshooting/document-limit): Co się dzieje, gdy limit dokumentów w twoim planie wstrzymuje synchronizację, oraz jak zwolnić miejsce lub uaktualnić, aby wznowić.
- [Osiągnięto dzienny limit przetwarzania](https://nordvec.com/pl/docs/guides/troubleshooting/daily-processing-limit): Co się dzieje, gdy dzienny limit przetwarzania w twojej przestrzeni roboczej wstrzymuje synchronizację i kiedy zostanie wznowiona.


---

# Ponownie połącz łącznik
Source: https://nordvec.com/pl/docs/guides/troubleshooting/reconnect-integration

Napraw błędy synchronizacji "uwierzytelnianie wygasło" i "dostęp został cofnięty", ponownie łącząc dotknięty łącznik.



Gdy synchronizacja zgłasza komunikat **„Twoja autentykacja wygasła”** lub **„Twój dostęp został cofnięty”**, Nordvec nie może już działać w Twoim imieniu u dostawcy. Połączenie samo w sobie wymaga odnowienia; ponowienie synchronizacji bez ponownego połączenia nie pomoże.

## Dlaczego to się dzieje [#dlaczego-to-się-dzieje]

* Dostawca unieważnił długoterminowe poświadczenia, które posiada Nordvec. Niektórzy dostawcy robią to według stałego harmonogramu, inni po okresie braku aktywności.
* Zmieniłeś hasło u dostawcy, co często cofa dostęp wszystkim podłączonym aplikacjom.
* Ty (lub administrator przestrzeni roboczej) cofnąłeś dostęp Nordvec w ustawieniach bezpieczeństwa lub podłączonych aplikacji dostawcy.
* Dostawca zmienił swoją politykę bezpieczeństwa (na przykład po podejrzanej aktywności na Twoim koncie) i unieważnił istniejące uprawnienia.

## Jak to naprawić [#jak-to-naprawić]

1. Otwórz **Łączniki** w Nordvec.
2. Znajdź dotknięty łącznik. Wyświetla on stan błędu zgłoszony przez ostatnią synchronizację oraz przycisk **Ponownie połącz** na swojej karcie.
3. Wybierz **Ponownie połącz** i zaloguj się do dostawcy tym **samym kontem**, którego użyłeś pierwotnie. Zaakceptuj wszystkie uprawnienia wymienione przez dostawcę; odmowa jednego z nich prowadzi do [błędu brakujących uprawnień](/docs/guides/troubleshooting/insufficient-scopes).

Ponowne połączenie jest również dostępne w dowolnym momencie z poziomu szczegółów łącznika, nie tylko po wystąpieniu błędu.

Ponowne połączenie zachowuje wszystko, co zostało już zsynchronizowane. Nie używaj **Rozłącz**, aby naprawić wygasłe logowanie: rozłączenie trwale usuwa wszystkie dokumenty, które zsynchronizował łącznik.

Jeśli zalogujesz się innym kontem niż to, z którym łącznik został pierwotnie skonfigurowany, Nordvec odrzuci ponowne połączenie i nic nie zmieni. Aby zmienić konto, rozłącz łącznik i połącz inne konto.

### Łączniki, których nie można ponownie połączyć w miejscu [#łączniki-których-nie-można-ponownie-połączyć-w-miejscu]

Guru, Notion, Zendesk, Freshdesk, Trello i e-conomic nie oferują opcji **Ponownie połącz**, ponieważ Nordvec nie może potwierdzić, że nowe logowanie należy do tego samego konta. W przypadku tych łączników rozłącz łącznik i połącz go ponownie. Rozłączenie usuwa dokumenty, które zsynchronizował, a następna synchronizacja zaimportuje je od nowa.

## Co dzieje się po ponownym połączeniu [#co-dzieje-się-po-ponownym-połączeniu]

Nowe logowanie zastępuje stare i błąd zostaje usunięty. Synchronizacja rozpoczyna się od razu, a dokumenty, które nie powiodły się, gdy połączenie było niedostępne, są ponawiane; elementy wymienione w sekcji **„Elementy, których nie można było zaimportować”** znikają, gdy zostaną pomyślnie zaimportowane.

Łączniki są podłączane na użytkownika: ponowne połączenie odnawia *Twoje* połączenie i nie wpływa na połączenia innych osób. Tylko osoba, która podłączyła łącznik, może go ponownie połączyć, w tym administratorzy przestrzeni roboczej: administrator nie może ponownie połączyć łącznika kolegi.


---

# Nadaj brakujące uprawnienia
Source: https://nordvec.com/pl/docs/guides/troubleshooting/insufficient-scopes

Napraw błędy synchronizacji "brakujące wymagane uprawnienia", ponownie łącząc łącznik i zatwierdzając każde żądane uprawnienie.



Gdy synchronizacja zgłasza komunikat **„Twoje konto nie ma wymaganych uprawnień”**, połączenie z dostawcą działa, ale przyznano mu mniej uprawnień (zakresów OAuth), niż łącznik potrzebuje do odczytu twojej zawartości. Jest to cecha samego przyznania uprawnień, więc jedynym rozwiązaniem jest ponowne nawiązanie połączenia z pełnym zestawem uprawnień.

## Dlaczego tak się dzieje [#dlaczego-tak-się-dzieje]

* Uprawnienie zostało odrzucone podczas pierwotnego procesu łączenia. Niektórzy dostawcy pozwalają odznaczyć poszczególne uprawnienia na ekranie zgody.
* Łącznik zyskał nową funkcję, która wymaga dodatkowego uprawnienia, a twoje starsze przyznanie uprawnień jest sprzed tej zmiany.
* Administrator przestrzeni roboczej ograniczył, jakie uprawnienia mogą mieć aplikacje zewnętrzne, lub dostawca wymaga zatwierdzenia przez administratora dla niektórych z nich.

## Jak to naprawić [#jak-to-naprawić]

1. Otwórz **Connectors** w Nordvec.
2. Znajdź dotknięty łącznik i wybierz **Reconnect** na jego karcie.
3. Zaloguj się na to samo konto, którego użyłeś pierwotnie, a na ekranie zgody dostawcy zatwierdź **wszystkie** żądane uprawnienia. Każde z nich odpowiada konkretnej potrzebie, zazwyczaj odczytowi dokumentów, plików lub wiadomości, które łącznik synchronizuje; na liście nie ma żadnych opcjonalnych dodatków.

Ponowne łączenie zachowuje już zsynchronizowane dokumenty. Guru, Notion, Zendesk, Freshdesk, Trello i e-conomic nie mogą być ponownie połączone w miejscu; dla tych łączników odłącz i połącz ponownie, co usunie zsynchronizowane dokumenty i zaimportuje je od nowa.

Jeśli na ekranie zgody pojawi się informacja, że administrator musi zatwierdzić aplikację, prześlij prośbę do swojego administratora przestrzeni roboczej. Dostawcy z procesem zatwierdzania przez administratora (na przykład organizacje Google Workspace i Microsoft 365 lub przestrzenie robocze Slack z zatwierdzaniem aplikacji) blokują przyznanie uprawnień, dopóki administrator ich nie zatwierdzi, a ponowne łączenie przed tą akceptacją spowoduje ten sam błąd.

## Co dzieje się po ponownym połączeniu [#co-dzieje-się-po-ponownym-połączeniu]

Nowe przyznanie uprawnień zastępuje stare, błąd znika, a synchronizacja rozpoczyna się od razu. Elementy, które wcześniej kończyły się niepowodzeniem z powodu błędów uprawnień, są ponawiane.


---

# Osiągnięto limit dokumentów
Source: https://nordvec.com/pl/docs/guides/troubleshooting/document-limit

Co się dzieje, gdy limit dokumentów w twoim planie wstrzymuje synchronizację, oraz jak zwolnić miejsce lub uaktualnić, aby wznowić.



Gdy synchronizacja zgłasza komunikat **„Osiągnąłeś limit dokumentów w swoim planie”**, połączenie jest sprawne i nic nie zawiodło po stronie dostawcy. Twój korpus osiągnął maksymalną liczbę dokumentów dozwoloną w ramach twojego planu, dlatego import został wstrzymany, zamiast usuwać treści bez powiadomienia.

## Co obejmuje limit [#co-obejmuje-limit]

Limit dotyczy dokumentów przechowywanych w twoim korpusie ze wszystkich źródeł: synchronizacji łączników, przesyłania plików oraz dokumentów wysyłanych przez API. Został wprowadzony, aby koszty indeksowania i wyszukiwania były przewidywalne. Jest to limit na przestrzeń roboczą, a nie na poszczególne łączniki.

## Jak wznowić synchronizację [#jak-wznowić-synchronizację]

Wykonaj jedną z poniższych czynności:

* **Zwolnij miejsce.** Usuń dokumenty, których już nie potrzebujesz, lub odłącz źródło, którego treści nie chcesz indeksować. Usunięcie dokumentu powoduje jego natychmiastowe usunięcie z indeksu.
* **Ulepsz swój plan lub dodaj miejsca.** Limit jest ustalany na jedno miejsce, a wyższe plany pozwalają na przechowywanie większej liczby dokumentów na miejsce.

Nie musisz ręcznie wznawiać synchronizacji: następna zaplanowana synchronizacja wykryje zwolnioną przestrzeń i wznowi działanie od miejsca, w którym została przerwana. Możesz również ręcznie uruchomić synchronizację z karty łącznika, gdy tylko zwolni się miejsce.

## Co dzieje się z dokumentami, które nie zmieściły się [#co-dzieje-się-z-dokumentami-które-nie-zmieściły-się]

Nic nie ginie w źródle, dostawca pozostaje systemem źródłowym. Dokumenty, które nie mogły zostać zaimportowane, zostaną pobrane podczas kolejnej udanej synchronizacji, gdy tylko zwolni się miejsce.


---

# Osiągnięto dzienny limit przetwarzania
Source: https://nordvec.com/pl/docs/guides/troubleshooting/daily-processing-limit

Co się dzieje, gdy dzienny limit przetwarzania w twojej przestrzeni roboczej wstrzymuje synchronizację i kiedy zostanie wznowiona.



Gdy synchronizacja zgłasza komunikat **„Twoja przestrzeń robocza osiągnęła dzisiejszy limit przetwarzania”**, połączenie jest sprawne i nic nie uległo awarii po stronie dostawcy. Twoja przestrzeń robocza przetworzyła tyle nowych treści w ciągu jednego dnia, ile pozwala jej limit, dlatego import został wstrzymany, zamiast odrzucać poszczególne elementy.

## Co obejmuje limit [#co-obejmuje-limit]

Limit uwzględnia treść przetworzoną do indeksowania ze wszystkich źródeł (synchronizacje łączników, przesyłanie plików, dokumenty wysyłane przez API) w ciągu jednego dnia kalendarzowego, mierzonego w UTC. Został wprowadzony, aby pierwsza synchronizacja dużego źródła nie trwała w nieskończoność w ciągu jednego dnia. Niezmieniona treść nie jest ponownie liczona, dlatego po początkowym imporcie przestrzeń robocza rzadko zbliża się do limitu.

Limit to dzienny przydział na przestrzeń roboczą, który skaluje się wraz z liczbą miejsc, a każdy członek może wykorzystać swoją część dziennie. Dzięki temu duży import jednej osoby nie zużyje całego przydziału przestrzeni roboczej.

## Jak wznowić synchronizację [#jak-wznowić-synchronizację]

Nie musisz nic robić. Łącznik jest zaplanowany do ponownego uruchomienia po północy UTC, gdy resetuje się dzienny przydział, i kontynuuje od miejsca, w którym został zatrzymany. Komunikat o statusie znika po tym uruchomieniu.

Możesz również ręcznie uruchomić synchronizację z karty łącznika. Rozpocznie ona działanie od miejsca, w którym poprzednia została zatrzymana, gdy tylko przydział będzie dostępny.

## Co dzieje się z treścią, która nie została przetworzona [#co-dzieje-się-z-treścią-która-nie-została-przetworzona]

Nic nie ginie u źródła, dostawca pozostaje systemem nadrzędnym. Elementy, które nie mogły zostać przetworzone dzisiaj, zostaną pobrane podczas kolejnego uruchomienia.