# Context pack: Troubleshooting Source: https://nordvec.com/cs/docs/guides/troubleshooting Pack: https://nordvec.com/cs/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. [Errors and rate limits](https://nordvec.com/cs/docs/guides/errors-and-rate-limits) (builds on) 2. [Troubleshooting](https://nordvec.com/cs/docs/guides/troubleshooting) (this guide) 3. [Reconnect a connector](https://nordvec.com/cs/docs/guides/troubleshooting/reconnect-integration) (linked from this guide) 4. [Grant missing permissions](https://nordvec.com/cs/docs/guides/troubleshooting/insufficient-scopes) (linked from this guide) 5. [Document limit reached](https://nordvec.com/cs/docs/guides/troubleshooting/document-limit) (linked from this guide) 6. [Daily processing limit reached](https://nordvec.com/cs/docs/guides/troubleshooting/daily-processing-limit) (linked from this guide) --- # Errors and rate limits Source: https://nordvec.com/cs/docs/guides/errors-and-rate-limits The one error envelope every failed request returns, the rate-limit headers, and how to retry a write safely. Every endpoint fails the same way, so a client handles errors, rate limits and retries once and reuses that code everywhere, including over [MCP](/docs/guides/mcp). ## The error envelope [#the-error-envelope] Every non-2xx response is one JSON object: ```json { "defined": false, "code": "TOO_MANY_REQUESTS", "message": "Too many requests", "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 } } ``` * `code` is the HTTP-level error, for example `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BAD_REQUEST` or `TOO_MANY_REQUESTS`. * `data.reason`, when present, is a finer machine-readable reason such as `auth.key_not_found` or `rate_limit.exceeded`. Branch on it rather than on `message`, which is for people and may change. * `defined` is `true` when the operation lists that error in the [API reference](/docs/api), and `false` for errors any request can meet (authentication, rate limits, an unknown route). * A validation failure answers `BAD_REQUEST` with the problems in `data.formErrors` and `data.fieldErrors`. Every response also carries an `X-Request-ID`. Quote it when you contact support, and we can find that exact request. ## Common statuses [#common-statuses] | Status | Code | What to do | | ------ | ----------------------- | --------------------------------------------------------------------- | | `400` | `BAD_REQUEST` | Fix the request; `data.fieldErrors` names the fields | | `401` | `UNAUTHORIZED` | Send a valid key or session | | `403` | `FORBIDDEN` | The key lacks the scope or the role the operation needs | | `404` | `NOT_FOUND` | The resource does not exist, or you are not allowed to see it | | `409` | `CONFLICT` | A duplicate write is still in flight; retry shortly | | `413` | `PAYLOAD_TOO_LARGE` | The request body is over 1 MB; split a bulk push into smaller batches | | `422` | `UNPROCESSABLE_CONTENT` | The request is well formed but cannot be applied | | `429` | `TOO_MANY_REQUESTS` | Wait for `Retry-After`, then retry | ## Rate limits [#rate-limits] Every response states the limit it was counted against, in two forms: * the `X-RateLimit-*` headers; * the IETF structured fields `RateLimit` (live state: `r` is the requests remaining, `t` the seconds until the window resets) and `RateLimit-Policy` (the quota: `q` is the limit, `w` the window in seconds). A `429` also carries `Retry-After` in seconds and `data.retryAfterMs`. Wait at least that long before the next request; retrying sooner is counted and refused again. ## Retrying writes safely [#retrying-writes-safely] A write operation that lists an `Idempotency-Key` header in the [API reference](/docs/api) can be retried without doing the work twice. Send one key per logical write and repeat the same key on every retry: * the same key with the same body within 24 hours replays the stored response; * the same key with a different body is refused with `422`; * a duplicate that arrives while the first is still running gets `409`. An operation without the header is not idempotent, so retry it only when you know the first attempt did not land. --- # Troubleshooting Source: https://nordvec.com/cs/docs/guides/troubleshooting Fixes for the sync errors and plan limits you can meet, each starting from the message you see. Each page starts from the message Nordvec shows you, explains why it appears and walks through the fix. For errors an API request returns, see [Errors and rate limits](/docs/guides/errors-and-rate-limits). - [Reconnect a connector](https://nordvec.com/cs/docs/guides/troubleshooting/reconnect-integration): Fix "authentication has expired" and "access has been revoked" sync errors by reconnecting the affected connector. - [Grant missing permissions](https://nordvec.com/cs/docs/guides/troubleshooting/insufficient-scopes): Fix "missing required permissions" sync errors by reconnecting the connector and approving every requested permission. - [Document limit reached](https://nordvec.com/cs/docs/guides/troubleshooting/document-limit): What happens when your plan's document limit pauses syncing, and how to free space or upgrade to resume. - [Daily processing limit reached](https://nordvec.com/cs/docs/guides/troubleshooting/daily-processing-limit): What happens when your workspace's daily processing limit pauses syncing, and when it resumes. --- # Reconnect a connector Source: https://nordvec.com/cs/docs/guides/troubleshooting/reconnect-integration Fix "authentication has expired" and "access has been revoked" sync errors by reconnecting the affected connector. When a sync reports **"Your authentication has expired"** or **"Your access has been revoked"**, Nordvec can no longer act on your behalf at the provider. The connection itself needs to be renewed; retrying the sync without reconnecting will not help. ## Why this happens [#why-this-happens] * The provider expired the long-lived credential Nordvec holds. Some providers do this on a fixed schedule, others after a period of inactivity. * You changed your password at the provider, which commonly revokes all connected apps. * You (or a workspace admin) revoked Nordvec's access from the provider's connected-apps or security settings. * The provider rotated its security policy (for example after suspicious activity on your account) and invalidated existing grants. ## How to fix it [#how-to-fix-it] 1. Open **Connectors** in Nordvec. 2. Find the affected connector. It shows the error state reported by the last sync, and a **Reconnect** button on its card. 3. Choose **Reconnect** and sign in to the provider with the **same account** you originally connected. Approve every permission the provider lists; declining one leads to a [missing-permissions error](/docs/guides/troubleshooting/insufficient-scopes) instead. Reconnect is also available from the connector's details at any time, not only after an error. Reconnecting keeps everything already synced. Do not use **Disconnect** to fix an expired sign-in: disconnecting permanently deletes every document the connector synced. If you sign in with a different account than the one the connector was set up with, Nordvec refuses the reconnect and changes nothing. To switch accounts, disconnect the connector and connect the other account instead. ### Connectors that cannot be reconnected in place [#connectors-that-cannot-be-reconnected-in-place] Guru, Notion, Zendesk, Freshdesk, Trello and e-conomic do not offer **Reconnect**, because Nordvec cannot confirm that a new sign-in belongs to the same account. For these, disconnect the connector and connect it again. Disconnecting deletes the documents it synced, and the next sync imports them again from the start. ## What happens after reconnecting [#what-happens-after-reconnecting] The new sign-in replaces the old one and the error clears. A sync starts right away, and documents that failed while the connection was down are retried; the items listed under **"Items that could not be imported"** clear as they import successfully. Connectors are connected per user: reconnecting renews *your* connection and does not affect anyone else's. Only the person who connected a connector can reconnect it, and that includes workspace admins: an admin cannot reconnect a colleague's connector. --- # Grant missing permissions Source: https://nordvec.com/cs/docs/guides/troubleshooting/insufficient-scopes Fix "missing required permissions" sync errors by reconnecting the connector and approving every requested permission. When a sync reports **"Your account is missing required permissions"**, the connection to the provider works, but it was granted fewer permissions (OAuth scopes) than the connector needs to read your content. This is a property of the grant itself, so the only fix is to redo the connection with the full set of permissions. ## Why this happens [#why-this-happens] * A permission was declined during the original connection flow. Some providers let you untick individual permissions on the consent screen. * The connector gained a capability that needs an additional permission, and your older grant predates it. * A workspace admin restricted which permissions third-party apps may hold, or the provider requires admin approval for some of them. ## How to fix it [#how-to-fix-it] 1. Open **Connectors** in Nordvec. 2. Find the affected connector and choose **Reconnect** on its card. 3. Sign in with the same account you originally connected, and on the provider's consent screen approve **all** requested permissions. Each one maps to a concrete need, typically reading the documents, files, or messages the connector syncs; there are no optional extras in the list. Reconnecting keeps the documents already synced. Guru, Notion, Zendesk, Freshdesk, Trello and e-conomic cannot be reconnected in place; for those, disconnect and connect again, which deletes the synced documents and imports them again from the start. If the consent screen says an administrator must approve the app, forward the request to your workspace admin. Providers with admin-consent flows (for example Google Workspace and Microsoft 365 organizations, or Slack workspaces with app approval) block the grant until an admin allows it, and reconnecting before that approval will produce the same error. ## What happens after reconnecting [#what-happens-after-reconnecting] The new grant replaces the old one, the error clears, and a sync starts right away. Items that previously failed with permission errors are retried. --- # Document limit reached Source: https://nordvec.com/cs/docs/guides/troubleshooting/document-limit What happens when your plan's document limit pauses syncing, and how to free space or upgrade to resume. When a sync reports **"You've reached your plan's document limit"**, the connection is healthy and nothing failed at the provider. Your corpus is simply at the maximum number of documents your plan allows, so importing paused rather than dropping content silently. ## What the limit covers [#what-the-limit-covers] The limit counts documents stored in your corpus across all sources: connector syncs, uploads, and documents pushed through the API. It exists to keep indexing and search costs predictable; it is a per-workspace allowance, not a per-connector one. ## How to resume syncing [#how-to-resume-syncing] Do either of the following: * **Free space.** Delete documents you no longer need, or disconnect a source whose content you do not want indexed. Deleting a document removes it from the index immediately. * **Upgrade your plan or add seats.** The allowance is set per seat, and higher plans allow more documents per seat. No manual restart is needed afterwards: the next scheduled sync detects the freed capacity and resumes where it left off. You can also trigger a sync manually from the connector's card once space is available. ## What happens to documents that did not fit [#what-happens-to-documents-that-did-not-fit] Nothing is lost at the source; the provider remains the system of record. Documents that could not be imported are picked up by the next successful sync once capacity allows. --- # Daily processing limit reached Source: https://nordvec.com/cs/docs/guides/troubleshooting/daily-processing-limit What happens when your workspace's daily processing limit pauses syncing, and when it resumes. When a sync reports **"Your workspace reached today's processing limit"**, the connection is healthy and nothing failed at the provider. Your workspace has processed as much new content in one day as its limit allows, so importing paused rather than continuing to be rejected item by item. ## What the limit covers [#what-the-limit-covers] The limit counts the content processed for indexing across all sources (connector syncs, uploads, documents pushed through the API) in one calendar day, measured in UTC. It exists to keep a first sync of a large source from running unbounded on a single day; unchanged content never counts again, so after the initial import a workspace rarely comes near it. The limit is a per-workspace allowance that scales with the number of seats, and each member can use a share of it per day, so one person's large import cannot use up the whole workspace's allowance. ## How syncing resumes [#how-syncing-resumes] Nothing to do. The connector is scheduled to run again after midnight UTC, when the day's allowance resets, and it continues from where it stopped. The status message clears on that run. You can also trigger a sync manually from the connector's card; it will pick up where the previous one stopped once the allowance is available. ## What happens to content that was not processed [#what-happens-to-content-that-was-not-processed] Nothing is lost at the source; the provider remains the system of record. Items that could not be processed today are picked up by the next run.