# Context pack: Errores y límites de frecuencia Source: https://nordvec.com/es/docs/guides/errors-and-rate-limits Pack: https://nordvec.com/es/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. [Errores y límites de frecuencia](https://nordvec.com/es/docs/guides/errors-and-rate-limits) (this guide) 2. [MCP](https://nordvec.com/es/docs/guides/mcp) (linked from this guide) --- # Errores y límites de frecuencia Source: https://nordvec.com/es/docs/guides/errors-and-rate-limits El sobre de error único que devuelve cada solicitud fallida, los encabezados de límite de frecuencia y cómo reintentar una escritura de forma segura. Cada endpoint falla de la misma manera, por lo que un cliente maneja errores, límites de tasa y reintentos una vez y reutiliza ese código en todas partes, incluso sobre [MCP](/docs/guides/mcp). ## El sobre de error [#el-sobre-de-error] Toda respuesta que no sea 2xx es un objeto JSON: ```json { "defined": false, "code": "TOO_MANY_REQUESTS", "message": "Too many requests", "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 } } ``` * `code` es el error a nivel HTTP, por ejemplo `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BAD_REQUEST` o `TOO_MANY_REQUESTS`. * `data.reason`, cuando está presente, es una razón más precisa legible por máquina, como `auth.key_not_found` o `rate_limit.exceeded`. Haz branching sobre ella en lugar de sobre `message`, que es para personas y puede cambiar. * `defined` es `true` cuando la operación lista ese error en la [referencia de la API](/docs/api), y `false` para errores que cualquier solicitud puede encontrar (autenticación, límites de tasa, una ruta desconocida). * Un fallo de validación responde `BAD_REQUEST` con los problemas en `data.formErrors` y `data.fieldErrors`. Toda respuesta también lleva un `X-Request-ID`. Cítalo cuando contactes con soporte, y podremos encontrar esa solicitud exacta. ## Estados comunes [#estados-comunes] | Estado | Código | Qué hacer | | ------ | ----------------------- | ----------------------------------------------------------------------------------- | | `400` | `BAD_REQUEST` | Corrige la solicitud; `data.fieldErrors` nombra los campos | | `401` | `UNAUTHORIZED` | Envía una clave o sesión válida | | `403` | `FORBIDDEN` | La clave carece del ámbito o el rol que necesita la operación | | `404` | `NOT_FOUND` | El recurso no existe, o no tienes permiso para verlo | | `409` | `CONFLICT` | Una escritura duplicada aún está en curso; reintenta en breve | | `413` | `PAYLOAD_TOO_LARGE` | El cuerpo de la solicitud supera 1 MB; divide un envío masivo en lotes más pequeños | | `422` | `UNPROCESSABLE_CONTENT` | La solicitud está bien formada pero no se puede aplicar | | `429` | `TOO_MANY_REQUESTS` | Espera `Retry-After`, luego reintenta | ## Límites de tasa [#límites-de-tasa] Cada respuesta indica el límite contra el que se contó, en dos formas: * los encabezados `X-RateLimit-*`; * los campos estructurados IETF `RateLimit` (estado en vivo: `r` son las solicitudes restantes, `t` los segundos hasta que se reinicie la ventana) y `RateLimit-Policy` (la cuota: `q` es el límite, `w` la ventana en segundos). Un `429` también lleva `Retry-After` en segundos y `data.retryAfterMs`. Espera al menos ese tiempo antes de la siguiente solicitud; reintentar antes se cuenta y se rechaza de nuevo. ## Reintentos de escrituras de forma segura [#reintentos-de-escrituras-de-forma-segura] Una operación de escritura que lista un encabezado `Idempotency-Key` en la [referencia de la API](/docs/api) se puede reintentar sin realizar el trabajo dos veces. Envía una clave por cada escritura lógica y repite la misma clave en cada reintento: * la misma clave con el mismo cuerpo en un plazo de 24 horas reproduce la respuesta almacenada; * la misma clave con un cuerpo diferente se rechaza con `422`; * un duplicado que llega mientras la primera aún se está ejecutando recibe `409`. Una operación sin el encabezado no es idempotente, así que reinténtala solo cuando sepas que el primer intento no se completó. --- # MCP Source: https://nordvec.com/es/docs/guides/mcp Conecta un agente de IA a la base de conocimiento de tu espacio de trabajo a través del Model Context Protocol con una clave API. Nordvec implementa el [Model Context Protocol](https://modelcontextprotocol.io) (MCP), por lo que un agente o asistente que hable MCP puede descubrir las operaciones de tu espacio de trabajo como herramientas y llamarlas de forma nativa, sin necesidad de un documento OpenAPI para razonar sobre ellas. Hay dos servidores: | Servidor | URL | Autenticación | Qué expone | | -------------------- | -------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Documentación | `https://nordvec.com/api/mcp` | ninguna | Estas guías y el catálogo de conectores, para un agente que se está integrando con Nordvec | | Base de conocimiento | `https://nordvec.com/api/v1/mcp` | clave API | Los documentos de tu espacio de trabajo, búsqueda e ingesta: las mismas operaciones que la [API REST](/docs/guides/authentication) | Ambos se ejecutan en la UE, en la misma infraestructura que el resto de la API. ## Conectar un cliente [#conectar-un-cliente] Apunta un cliente MCP al servidor de la base de conocimiento con tu clave API como token de portador. La mayoría de los clientes aceptan un bloque de configuración como este: ```json { "mcpServers": { "nordvec": { "url": "https://nordvec.com/api/v1/mcp", "headers": { "Authorization": "Bearer nv_eu_live_your_api_key" } } } } ``` El servidor es HTTP Streamable sin estado: cada mensaje es un `POST` que transporta una solicitud JSON-RPC, y la respuesta llega en el cuerpo de la respuesta. No hay sesiones que mantener ni flujos iniciados por el servidor, por lo que un `GET` en la URL responde con `405`, y un `POST` cuyo `Content-Type` no es `application/json` responde con `415` antes de leer el cuerpo. Solo una clave API puede usar el servidor de la base de conocimiento. Se rechaza una sesión de navegador iniciada, y cada herramienta necesita el ámbito de clave que requiere la operación REST correspondiente, por lo que una clave creada para un trabajo puede realizar exactamente ese trabajo a través de MCP también. El servidor se autentica con una clave estática de portador y no ofrece descubrimiento OAuth. Un cliente que te permita establecer encabezados de solicitud (agentes de codificación, extensiones de IDE, el Inspector MCP en modo de encabezado) se conecta como se muestra arriba; un cliente alojado que solo admita el flujo de autorización OAuth no puede conectarse todavía. Un cliente que envíe el encabezado `MCP-Protocol-Version` recibirá una respuesta bajo esa versión cuando el servidor la soporte (`2025-06-18` y `2024-11-05`) y será rechazado con `400` cuando no la soporte, por lo que un desajuste de versión se informa en el primer mensaje en lugar de como una respuesta mal formada más tarde. ## Herramientas [#herramientas] Las herramientas se derivan de la API REST, una herramienta por operación que una clave API puede llamar. El nombre de una herramienta es la ruta del contrato de la operación en *snake case*, omitiendo un segmento que repita el anterior. La columna de ámbito es el ámbito de clave API que necesita la herramienta: | Operación REST | Ruta del contrato | Herramienta MCP | Ámbito | | ------------------------------------- | ------------------------------------ | ---------------------------------- | -------------- | | `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` es el catálogo autoritativo: muestra una clave solo las herramientas que admiten sus ámbitos, y la descripción de cada herramienta nombra el ámbito que requiere. El `inputSchema` de una herramienta es el esquema de solicitud de la operación y, cuando la operación devuelve un objeto, su `outputSchema` es el esquema de respuesta y los resultados incluyen `structuredContent` junto al texto JSON. Llamar a una herramienta que los ámbitos de la clave no admiten responde con un error de herramienta que nombra `FORBIDDEN`, el mismo rechazo que da la ruta REST, por lo que un cliente que tenga una lista en caché de otra clave entiende el motivo en lugar de que la herramienta falte. ## Reintentando una escritura [#reintentando-una-escritura] `document_push` y `document_push_bulk` aceptan un argumento opcional `idempotencyKey`, así un agente o cliente que reintente un envío no indexa dos veces los documentos. Envía una clave por cada escritura lógica, como un UUID, y repite la misma clave con los mismos argumentos en cada reintento: * la misma clave con los mismos argumentos en un plazo de 24 horas devuelve el resultado de la primera llamada sin volver a ejecutarla; * la misma clave con argumentos diferentes se rechaza: el resultado de la herramienta tiene `isError: true` y nombra `UNPROCESSABLE_CONTENT`; * un reintento que llega mientras la primera llamada aún se está ejecutando se rechaza de la misma manera, nombrando `CONFLICT`; reinténtalo tras una breve pausa. Una clave tiene entre 1 y 256 caracteres ASCII imprimibles y pertenece a la clave API que la envió: otra clave API que use el mismo valor ejecutará su propia escritura. Una clave utilizada con la cabecera REST `Idempotency-Key` no se comparte con la herramienta MCP, por lo que una llamada de la herramienta que la reutilice será rechazada con `UNPROCESSABLE_CONTENT`. Una llamada sin el argumento se ejecutará cada vez, por eso estas herramientas no declaran `idempotentHint`. El comportamiento REST se describe en [reintentar escrituras de forma segura](/docs/guides/errors-and-rate-limits). ## Límites y errores [#límites-y-errores] Una llamada a una herramienta consume el mismo cubo de límite de tasa que la operación REST correspondiente, y cualquier otro mensaje en el punto final consume su propio cubo. Los encabezados `X-RateLimit-*`, la respuesta `429` con su `Retry-After`, y el sobre de error son los mismos que en la [API REST](/docs/guides/errors-and-rate-limits), por lo que un cliente que ya los maneje para REST los maneja aquí también. Una llamada fallida a una herramienta devuelve un resultado de herramienta MCP con `isError: true` cuyo texto es el cuerpo de error REST (`code`, `message`, `data`); los fallos de validación llevan la misma forma `fieldErrors` que devuelve la API REST. Un error JSON-RPC está reservado para el protocolo en sí: un cuerpo no analizable, un método desconocido o un fallo del servidor. Los cuerpos de solicitud están limitados a 1 MB, el mismo límite que las rutas REST. ## Un primer intercambio [#un-primer-intercambio] ```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"}}}' ``` ## El servidor de documentación [#el-servidor-de-documentación] El servidor de documentación en `/api/mcp` no necesita clave. Ofrece `list_guides`, `get_guide`, `search_docs` y `list_connectors`, por lo que un agente que esté construyendo una aplicación sobre la API puede leer estas guías directamente. Está limitado por IP como los demás puntos finales públicos.