# Context pack: Errori e limiti di frequenza Source: https://nordvec.com/it/docs/guides/errors-and-rate-limits Pack: https://nordvec.com/it/docs/packs/errors-and-rate-limits 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) (this guide) 2. [MCP](https://nordvec.com/it/docs/guides/mcp) (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. --- # MCP Source: https://nordvec.com/it/docs/guides/mcp Collega un agente IA alla tua base di conoscenza dell'area di lavoro tramite il Model Context Protocol con una chiave API. Nordvec supporta il [Model Context Protocol](https://modelcontextprotocol.io) (MCP), quindi un agente o un assistente che parla MCP può scoprire le operazioni della tua area di lavoro come strumenti e richiamarle in modo nativo, senza un documento OpenAPI su cui ragionare. Ci sono due server: | Server | URL | Autenticazione | Cosa espone | | ------------------ | -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Documentazione | `https://nordvec.com/api/mcp` | nessuna | Queste guide e il catalogo dei connettori, per un agente che si integra con Nordvec | | Base di conoscenza | `https://nordvec.com/api/v1/mcp` | chiave API | I documenti, la ricerca e l'acquisizione della tua area di lavoro: le stesse operazioni della [API REST](/docs/guides/authentication) | Entrambi sono ospitati nell'UE, su la stessa infrastruttura del resto dell'API. ## Collegare un client [#collegare-un-client] Punta un client MCP al server della knowledge base con la tua chiave API come bearer token. La maggior parte dei client accetta un blocco di configurazione come questo: ```json { "mcpServers": { "nordvec": { "url": "https://nordvec.com/api/v1/mcp", "headers": { "Authorization": "Bearer nv_eu_live_your_api_key" } } } } ``` Il server è HTTP Streamable stateless: ogni messaggio è una `POST` che trasporta una richiesta JSON-RPC, e la risposta arriva nel corpo della risposta. Non ci sono sessioni da mantenere e nessuno stream iniziato dal server, quindi una `GET` sull'URL risponde con `405`, e una `POST` il cui `Content-Type` non è `application/json` risponde con `415` prima che il corpo venga letto. Solo una chiave API può utilizzare il server della knowledge base. Una sessione del browser con accesso viene rifiutata, e ogni strumento necessita dello scope della chiave API che corrisponde all'operazione REST, quindi una chiave creata per un lavoro può fare esattamente quel lavoro anche tramite MCP. Il server autentica con una chiave bearer statica e non offre la scoperta OAuth. Un client che ti permette di impostare le intestazioni delle richieste (agenti di codifica, estensioni per IDE, l'MCP Inspector in modalità intestazione) si collega come mostrato sopra; un client ospitato che supporta solo il flusso di autorizzazione OAuth non può ancora collegarsi. Un client che invia l'intestazione `MCP-Protocol-Version` riceve una risposta con quella versione quando il server la supporta (`2025-06-18` e `2024-11-05`) e viene rifiutato con `400` quando non la supporta, quindi una discrepanza di versione viene segnalata al primo messaggio piuttosto che come risposta malformata in seguito. ## Strumenti [#strumenti] Gli strumenti sono derivati dall'API REST, uno strumento per ogni operazione che una chiave API può chiamare. Il nome di uno strumento è il percorso del contratto dell'operazione in snake case, con un segmento che ripete quello precedente eliminato. La colonna scope è lo scope della chiave API di cui lo strumento ha bisogno: | Operazione REST | Percorso del contratto | Strumento MCP | Ambito | | ------------------------------------- | ------------------------------------ | ---------------------------------- | -------------- | | `POST /documents/search` | `documents.search` | `documents_search` | `search:read` | | `GET /documents/{id}` | `documents.get` | `documents_get` | `search:read` | | `POST /documents/batch` | `documents.batchGet` | `documents_batch_get` | `search:read` | | `GET /documents/list` | `documents.list` | `documents_list` | `search:read` | | `POST /documents/push` | `documentPush.push` | `document_push` | `index:write` | | `POST /documents/push/bulk` | `documentPush.pushBulk` | `document_push_bulk` | `index:write` | | `POST /documents/push/permissions` | `documentPush.pushUpdatePermissions` | `document_push_update_permissions` | `index:write` | | `POST /documents/push/delete` | `documentPush.pushDelete` | `document_push_delete` | `index:delete` | | `GET /documents/push/status` | `documentPush.pushStatus` | `document_push_status` | `index:status` | | `GET /documents/push/upload` | `documentPush.pushUploadStatus` | `document_push_upload_status` | `index:status` | | `POST /documents/push/upload/restore` | `documentPush.pushUploadRestore` | `document_push_upload_restore` | `index:write` | | `GET /analytics/ingestion` | `analytics.ingestion` | `analytics_ingestion` | `index:status` | | `GET /quota/embedding` | `quota.embedding` | `quota_embedding` | `quota:read` | | `GET /analytics/usage` | `analytics.usage` | `analytics_usage` | `quota:read` | | `POST /tenant/audit-log/search` | `auditLog.list` | `audit_log_list` | `audit:read` | | `GET /tenant/audit-log/catalog` | `auditLog.catalog` | `audit_log_catalog` | `audit:read` | `tools/list` è il catalogo autorevole: mostra una chiave solo gli strumenti che i suoi scope ammettono, e la descrizione di ogni strumento indica lo scope che richiede. Il `inputSchema` di uno strumento è lo schema della richiesta dell'operazione e, dove l'operazione restituisce un oggetto, il suo `outputSchema` è lo schema della risposta e i risultati portano `structuredContent` insieme al testo JSON. La chiamata a uno strumento non ammesso dagli scope della chiave risponde con un errore dello strumento che indica `FORBIDDEN`, lo stesso rifiuto che dà la rotta REST, quindi un client che mantiene una lista memorizzata da un'altra chiave apprende il motivo piuttosto che semplicemente che lo strumento manca. ## Ripetizione di una scrittura [#ripetizione-di-una-scrittura] `document_push` e `document_push_bulk` accettano un argomento opzionale `idempotencyKey`, quindi un agente o client che ripete un push non indicizza i documenti due volte. Invia una chiave per ogni scrittura logica, come un UUID, e ripeti la stessa chiave con gli stessi argomenti ad ogni tentativo: * la stessa chiave con gli stessi argomenti entro 24 ore restituisce il risultato della prima chiamata senza eseguirla nuovamente; * la stessa chiave con argomenti diversi viene rifiutata: il risultato dello strumento è `isError: true` e riporta `UNPROCESSABLE_CONTENT`; * un tentativo di ripetizione che arriva mentre la prima chiamata è ancora in esecuzione viene rifiutato allo stesso modo, indicando `CONFLICT`; riprova dopo un breve intervallo. Una chiave è composta da 1 a 256 caratteri ASCII stampabili e appartiene alla chiave API che l'ha inviata: un'altra chiave API che utilizza lo stesso valore esegue una propria scrittura. Una chiave usata con l'header REST `Idempotency-Key` non è condivisa con lo strumento MCP, quindi una chiamata dello strumento che la riutilizza viene rifiutata con `UNPROCESSABLE_CONTENT`. Una chiamata senza l'argomento viene rieseguita ogni volta, motivo per cui questi strumenti non dichiarano `idempotentHint`. Il comportamento REST è descritto nella sezione [rieseguire scritture in sicurezza](/docs/guides/errors-and-rate-limits). ## Limiti e errori [#limiti-e-errori] Una chiamata a uno strumento attinge dallo stesso bucket di limitazione della frequenza dell'operazione REST corrispondente, e ogni altro messaggio sull'endpoint dal proprio bucket. Le intestazioni `X-RateLimit-*`, la risposta `429` con il suo `Retry-After`, e la struttura dell'errore sono le stesse dell'[API REST](/docs/guides/errors-and-rate-limits), quindi un client che già le gestisce per REST le gestisce anche qui. Una chiamata a uno strumento fallita restituisce un risultato dello strumento MCP con `isError: true` il cui testo è il corpo dell'errore REST (`code`, `message`, `data`); i fallimenti di validazione portano la stessa forma `fieldErrors` che restituisce l'API REST. Un errore JSON-RPC è riservato al protocollo stesso: un corpo non analizzabile, un metodo sconosciuto o un guasto del server. I corpi delle richieste sono limitati a 1 MB, lo stesso limite delle rotte REST. ## Un primo scambio [#un-primo-scambio] ```bash # Discover the tools your key can call curl https://nordvec.com/api/v1/mcp \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' # Search the workspace curl https://nordvec.com/api/v1/mcp \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"documents_search","arguments":{"query":"data retention policy"}}}' ``` ## Il server di documentazione [#il-server-di-documentazione] Il server di documentazione su `/api/mcp` non richiede alcuna chiave. Offre `list_guides`, `get_guide`, `search_docs` e `list_connectors`, quindi un agente che sta costruendo un'applicazione sull'API può leggere queste guide direttamente. È limitato per IP come gli altri endpoint pubblici.