# Context pack: Fel och begränsningar för anrop Source: https://nordvec.com/sv/docs/guides/errors-and-rate-limits Pack: https://nordvec.com/sv/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. [Fel och begränsningar för anrop](https://nordvec.com/sv/docs/guides/errors-and-rate-limits) (this guide) 2. [MCP](https://nordvec.com/sv/docs/guides/mcp) (linked from this guide) --- # Fel och begränsningar för anrop Source: https://nordvec.com/sv/docs/guides/errors-and-rate-limits Det enda felmeddelande som varje misslyckad förfrågan returnerar, gränshuvudena för anrop, och hur du säkert försöker igen med en skrivning. Varje slutpunkt misslyckas på samma sätt, så en klient hanterar fel, hastighetsbegränsningar och omsändningar en gång och återanvänder den koden överallt, inklusive över [MCP](/docs/guides/mcp). ## Felkuvertet [#felkuvertet] Varje icke-2xx-svar är ett JSON-objekt: ```json { "defined": false, "code": "TOO_MANY_REQUESTS", "message": "Too many requests", "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 } } ``` * `code` är HTTP-nivåfelet, till exempel `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BAD_REQUEST` eller `TOO_MANY_REQUESTS`. * `data.reason`, när det finns, är en mer detaljerad maskinläsbar orsak som `auth.key_not_found` eller `rate_limit.exceeded`. Grena på det i stället för på `message`, som är för människor och kan ändras. * `defined` är `true` när operationen listar det felet i [API-referensen](/docs/api), och `false` för fel som alla förfrågningar kan möta (autentisering, hastighetsbegränsningar, en okänd rutt). * Ett valideringsfel svarar `BAD_REQUEST` med problemen i `data.formErrors` och `data.fieldErrors`. Varje svar innehåller också ett `X-Request-ID`. Ange det när du kontaktar support, så kan vi hitta exakt den förfrågan. ## Vanliga statuskoder [#vanliga-statuskoder] | Status | Kod | Vad du ska göra | | ------ | ----------------------- | ------------------------------------------------------------------------ | | `400` | `BAD_REQUEST` | Åtgärda förfrågan; `data.fieldErrors` namnger fälten | | `401` | `UNAUTHORIZED` | Skicka en giltig nyckel eller session | | `403` | `FORBIDDEN` | Nyckeln saknar det omfång eller den roll som operationen kräver | | `404` | `NOT_FOUND` | Resursen finns inte, eller så har du inte behörighet att se den | | `409` | `CONFLICT` | En duplicerad skrivning är fortfarande pågående; försök igen om en stund | | `413` | `PAYLOAD_TOO_LARGE` | Förfrågningskroppen är över 1 MB; dela upp en bulkpush i mindre batcher | | `422` | `UNPROCESSABLE_CONTENT` | Förfrågan är välformulerad men kan inte tillämpas | | `429` | `TOO_MANY_REQUESTS` | Vänta i `Retry-After`, sedan försöker du igen | ## Hastighetsbegränsningar [#hastighetsbegränsningar] Varje svar anger den gräns som den räknades mot, i två former: * `X-RateLimit-*`-huvudena; * de IETF-strukturerade fälten `RateLimit` (aktuellt tillstånd: `r` är de återstående förfrågningarna, `t` sekunderna tills fönstret återställs) och `RateLimit-Policy` (kvoten: `q` är gränsen, `w` fönstret i sekunder). Ett `429` innehåller också `Retry-After` i sekunder och `data.retryAfterMs`. Vänta minst så länge innan nästa förfrågan; att försöka tidigare räknas och nekas igen. ## Säker omsändning av skrivningar [#säker-omsändning-av-skrivningar] En skrivoperation som listar en `Idempotency-Key`-huvud i [API-referensen](/docs/api) kan omsändas utan att arbetet utförs två gånger. Skicka en nyckel per logisk skrivning och upprepa samma nyckel vid varje omsändning: * samma nyckel med samma kropp inom 24 timmar spelar upp det lagrade svaret; * samma nyckel med en annan kropp nekas med `422`; * en duplicering som anländer medan den första fortfarande körs får `409`. En operation utan huvudet är inte idempotent, så omsänd den bara när du vet att det första försöket inte landade. --- # MCP Source: https://nordvec.com/sv/docs/guides/mcp Koppla en AI-agent till din kunskapsbas i arbetsytan via Model Context Protocol med en API-nyckel. Nordvec tillhandahåller [Model Context Protocol](https://modelcontextprotocol.io) (MCP), så en agent eller assistent som talar MCP kan upptäcka din arbetsytas operationer som verktyg och anropa dem direkt, utan att behöva resonera kring en OpenAPI-dokumentation. Det finns två servrar: | Server | URL | Autentisering | Vad den exponerar | | ------------- | -------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------- | | Dokumentation | `https://nordvec.com/api/mcp` | ingen | Dessa guider och anslutningskatalogen, för en agent som integrerar med Nordvec | | Kunskapsbas | `https://nordvec.com/api/v1/mcp` | API-nyckel | Din arbetsytas dokument, sökning och inmatning: samma operationer som i [REST API:t](/docs/guides/authentication) | Båda körs i EU, på samma infrastruktur som resten av API:t. ## Ansluta en klient [#ansluta-en-klient] Peka en MCP-klient mot kunskapsbasserven med din API-nyckel som bearer-token. De flesta klienter tar emot ett konfigurationsblock som detta: ```json { "mcpServers": { "nordvec": { "url": "https://nordvec.com/api/v1/mcp", "headers": { "Authorization": "Bearer nv_eu_live_your_api_key" } } } } ``` Servern är tillståndslös Streamable HTTP: varje meddelande är en `POST` som bär en JSON-RPC-förfrågan, och svaret kommer tillbaka i svarskroppen. Det finns inga sessioner att upprätthålla och ingen serverinitierad ström, så en `GET` på URL:en svarar `405`, och en `POST` vars `Content-Type` inte är `application/json` svarar `415` innan kroppen läses. Endast en API-nyckel kan använda kunskapsbasserven. En inloggad webbläsarsession nekas, och varje verktyg kräver samma nyckelomfång som motsvarande REST-operation, så en nyckel skapad för ett visst jobb kan utföra exakt det jobbet via MCP också. Servern autentiserar med en statisk bearer-nyckel och erbjuder inte OAuth-upptäckt. En klient som låter dig ställa in rubriker för förfrågningar (kodningsagenter, IDE-tillägg, MCP Inspektorn i rubrikläge) ansluter som visat ovan. En hostad klient som endast stöder OAuth-auktoriseringsflöde kan ännu inte ansluta. En klient som skickar `MCP-Protocol-Version`-rubriken får svar enligt den versionen när servern stöder den (`2025-06-18` och `2024-11-05`) och nekas med `400` när den inte gör det, så en versionskonflikt rapporteras vid första meddelandet istället för som ett felaktigt svar senare. ## Verktyg [#verktyg] Verktygen härleds från REST API:t, ett verktyg per operation som en API-nyckel får anropa. Ett verktygs namn är operationens kontraktväg i snake case, där ett segment som upprepar det föregående segmentet har tagits bort. Omfångskolumnen är det API-nyckelomfång som verktyget kräver: | REST-åtgärd | Kontraktsväg | MCP-verktyg | Omfång | | ------------------------------------- | ------------------------------------ | ---------------------------------- | -------------- | | `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` är den auktoritativa katalogen: den visar endast de verktyg som dess omfång tillåter, och varje verktygs beskrivning anger det omfång som krävs. Ett verktygs `inputSchema` är operationens förfrågansschema och, där operationen returnerar ett objekt, är dess `outputSchema` svarschemat och resultaten innehåller `structuredContent` tillsammans med JSON-texten. Ett anrop till ett verktyg som nyckelns omfång inte tillåter svarar med ett verktygsfel som anger `FORBIDDEN`, samma avslag som REST-rutten ger, så en klient som har en cachad lista från en annan nyckel får reda på varför istället för att verktyget saknas. ## Försök igen med en skrivning [#försök-igen-med-en-skrivning] `document_push` och `document_push_bulk` tar ett valfritt `idempotencyKey`-argument, så att en agent eller klient som försöker igen med en push inte indexerar dokumenten två gånger. Skicka en nyckel per logisk skrivning, till exempel ett UUID, och upprepa samma nyckel med samma argument vid varje nytt försök: * samma nyckel med samma argument inom 24 timmar returnerar det första anropets resultat utan att köra det igen; * samma nyckel med olika argument avvisas: verktygsresultatet har `isError: true` och namnger `UNPROCESSABLE_CONTENT`; * ett nytt försök som inkommer medan det första anropet fortfarande körs avvisas på samma sätt, och namnger `CONFLICT`; försök igen efter en kort fördröjning. En nyckel är 1 till 256 skrivbara ASCII-tecken och tillhör den API-nyckel som skickade den: en annan API-nyckel som använder samma värde kör sin egen skrivning. En nyckel som används med REST-huvudet `Idempotency-Key` delas inte med MCP-verktyget, så ett verktygsanrop som återanvänder den avvisas med `UNPROCESSABLE_CONTENT`. Ett anrop utan argumentet körs varje gång igen, vilket är anledningen till att dessa verktyg inte deklarerar `idempotentHint`. REST-beteendet beskrivs under [att försöka skriva på nytt på ett säkert sätt](/docs/guides/errors-and-rate-limits). ## Begränsningar och fel [#begränsningar-och-fel] Ett verktygsanrop drar från samma hastighetsbegränsningsbucket som motsvarande REST-operation, och alla andra meddelanden på slutpunkten drar från sin egen bucket. `X-RateLimit-*`-rubrikerna, `429`-svaret med dess `Retry-After`, och felkuvertet är desamma som i [REST API:t](/docs/guides/errors-and-rate-limits), så en klient som redan hanterar dem för REST hanterar dem här. Ett misslyckat verktygsanrop returnerar ett MCP-verktygsresultat med `isError: true` vars text är REST-felets kropp (`code`, `message`, `data`); valideringsfel har samma `fieldErrors`-form som REST API:t returnerar. Ett JSON-RPC-fel är reserverat för själva protokollet: en oformaterad kropp, en okänd metod eller ett serverfel. Förfråganskroppar är begränsade till 1 MB, samma gräns som REST-rutterna. ## Ett första utbyte [#ett-första-utbyte] ```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"}}}' ``` ## Dokumentationsservern [#dokumentationsservern] Dokumentationsservern på `/api/mcp` kräver ingen nyckel. Den erbjuder `list_guides`, `get_guide`, `search_docs` och `list_connectors`, så en agent som bygger en applikation på API:t kan läsa dessa guider direkt. Den är hastighetsbegränsad per IP-adress precis som de andra publika slutpunkterna.