> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nippy.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores comunes

> Errores del servidor MCP de Nippy y cómo resolverlos

Todas las respuestas de error incluyen un campo `detail` con contexto específico.

<Warning>
  Si reportas un error a [soporte@nippy.la](mailto:soporte@nippy.la), incluye el `request_id`, el campo `detail` y la acción que estabas ejecutando.
</Warning>

## Códigos HTTP

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    **Causa:** La API key falta, está mal escrita o no usa el prefijo `npk_`.

    **Solución:** Envía el header `X-API-Key` con una key válida.

    ```bash theme={null}
    curl https://ms.nippy.la/cognitive-layer/mcp \
      -H "X-API-Key: npk_tu_api_key_aqui"
    ```
  </Accordion>

  <Accordion title="403 Forbidden">
    **Causa:** La key no tiene permisos para la vertical, tool o recurso solicitado.

    **Solución:** Revisa permisos desde la consola y confirma que el recurso pertenece a tu negocio.

    ```json theme={null}
    {
      "error": "forbidden",
      "detail": "Key does not have access to this tool"
    }
    ```
  </Accordion>

  <Accordion title="429 Too Many Requests">
    **Causa:** El cliente envió demasiadas solicitudes en poco tiempo.

    **Solución:** Espera unos segundos y distribuye las llamadas en el tiempo.

    ```typescript theme={null}
    await new Promise(resolve => setTimeout(resolve, 2000))
    ```
  </Accordion>

  <Accordion title="500 Internal Server Error">
    **Causa:** Ocurrió un error interno al ejecutar la solicitud.

    **Solución:** Reintenta más tarde. Si persiste, reporta el `request_id`.

    ```json theme={null}
    {
      "error": "internal_server_error",
      "request_id": "req_abc123"
    }
    ```
  </Accordion>
</AccordionGroup>

## Errores comunes de tools

<AccordionGroup>
  <Accordion title="MCP tools require tenant-bound auth">
    **Causa:** La key no está ligada a un negocio específico.

    **Solución:** Usa una API key `npk_*` creada desde `https://console.nippy.la/settings/api-keys`.

    ```text theme={null}
    X-API-Key: npk_tu_api_key_aqui
    ```
  </Accordion>

  <Accordion title="Sin resultados en Analytics">
    **Causa:** No hay datos para el rango de fechas o el área consultada no contiene ese tipo de información.

    **Solución:** Prueba con un rango más amplio y confirma que la colección consultada sea la correcta.

    ```json theme={null}
    {
      "collection": "roulettesMaterializedView",
      "dateRange": "last_90_days"
    }
    ```
  </Accordion>

  <Accordion title="Roulette not found or does not belong to this business">
    **Causa:** El ID de ruleta no existe o pertenece a otro negocio.

    **Solución:** Usa `roulettes_list_roulettes` para obtener IDs válidos.

    ```text theme={null}
    Lista mis ruletas activas y sus IDs
    ```
  </Accordion>

  <Accordion title="Error de validación en retiros de Supply">
    **Causa:** El centro, producto o stock no cumple las validaciones del servidor.

    **Solución:** Verifica IDs con `supply_list_nippy_centers` y `supply_list_nippy_center_stocks` antes de reintentar.

    ```text theme={null}
    Muéstrame el stock disponible por centro antes de registrar el retiro
    ```
  </Accordion>
</AccordionGroup>