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

# Manejo de errores

> Mensajes de error comunes y consejos de depuración para la Analytics API, incluidos errores de autenticación, estructura de consultas y límites de tasa.

<div id="overview">
  ## Descripción general
</div>

La Analytics API devuelve mensajes de error detallados para ayudar a depurar consultas no válidas. En esta página se describen los errores más comunes y cómo resolverlos.

<div id="error-response-format">
  ## Formato de la respuesta de error
</div>

Cuando se produce un error, la API devuelve una respuesta de error con un mensaje descriptivo:

```json theme={null}
{
  "error": "Error message describing what went wrong"
}
```

<div id="common-errors">
  ## Errores comunes
</div>

<div id="authentication-errors">
  ### Errores de autenticación
</div>

<AccordionGroup>
  <Accordion title="Clave de servicio no válida">
    **Error:** `Invalid service key`

    **Cause:** La clave de servicio proporcionada no es válida o ha sido revocada.

    **Solution:**

    * Verifica que tu clave de servicio sea correcta
    * Comprueba que la clave de servicio no haya sido revocada
    * Genera una nueva clave de servicio si es necesario
  </Accordion>

  <Accordion title="Permisos insuficientes">
    **Error:** `Insufficient permissions`

    **Cause:** La clave de servicio no tiene los permisos necesarios para el endpoint al que estás llamando.

    **Solution:**

    * Actualiza los permisos de la clave de servicio en Team Settings
    * Consulta la [introducción a la API](/es/desktop/accounts/api-reference/api-introduction#required-permissions) para ver el permiso específico que requiere cada endpoint
  </Accordion>
</AccordionGroup>

<div id="query-structure-errors">
  ### Errores en la estructura de la consulta
</div>

<AccordionGroup>
  <Accordion title="Faltan selecciones">
    **Error:** `at least one field or aggregation is required`

    **Causa:** La solicitud de consulta no contiene ninguna selección ni agregación.

    **Solución:** Agrega al menos una selección a tu solicitud de consulta:

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      }
    ]
    ```
  </Accordion>

  <Accordion title="Fuente de datos no válida">
    **Error:** `invalid query table: QUERY_DATA_SOURCE_UNSPECIFIED`

    **Causa:** Es probable que haya un error tipográfico en el campo `data_source`.

    **Solución:** Verifica de nuevo la ortografía de tu fuente de datos. Las opciones válidas son:

    * `QUERY_DATA_SOURCE_USER_DATA`
    * `QUERY_DATA_SOURCE_CHAT_DATA`
    * `QUERY_DATA_SOURCE_COMMAND_DATA`
    * `QUERY_DATA_SOURCE_PCW_DATA`
  </Accordion>

  <Accordion title="Funciones de agregación mezcladas">
    **Error:** `all selection fields should have an aggregation function, or none of them should`

    **Causa:** Algunas selecciones tienen funciones de agregación y otras no.

    **Solución:** Agrega funciones de agregación a todas las selecciones o elimínalas de todas:

    **No válido:**

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      },
      {
        "field": "num_lines_accepted",
        "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
      }
    ]
    ```

    **Válido:**

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      },
      {
        "field": "num_lines_accepted",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      }
    ]
    ```
  </Accordion>
</AccordionGroup>

<div id="field-and-aggregation-errors">
  ### Errores de campos y agregación
</div>

<AccordionGroup>
  <Accordion title="Función de agregación no válida">
    **Error:** `invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUM`

    **Cause:** La función de agregación no es compatible con el tipo de campo especificado.

    **Solution:** Consulta la sección [Campos disponibles](/es/desktop/accounts/api-reference/custom-analytics#available-fields) para ver qué funciones de agregación son válidas para cada campo. Los campos de tipo cadena normalmente solo admiten `COUNT` y `UNSPECIFIED`.
  </Accordion>

  <Accordion title="Agregación de un campo distinct">
    **Error:** `tried to aggregate on a distinct field: distinct_developer_days. Consider aggregating on the non-distinct fields instead: [api_key date]`

    **Cause:** Los campos con el patrón "distinct\_\*" no se pueden usar en la sección de agregaciones.

    **Solution:** Usa los campos alternativos sugeridos para la agregación:

    **Invalid:**

    ```json theme={null}
    "aggregations": [
      {
        "field": "distinct_developer_days",
        "name": "distinct_developer_days"
      }
    ]
    ```

    **Valid:**

    ```json theme={null}
    "aggregations": [
      {
        "field": "api_key",
        "name": "api_key"
      },
      {
        "field": "date",
        "name": "date"
      }
    ]
    ```
  </Accordion>

  <Accordion title="Alias de campo duplicados">
    **Error:** `duplicate field alias for selection/aggregation: num_acceptances`

    **Cause:** Varias selecciones o agregaciones tienen el mismo nombre.

    **Solution:** Asegúrate de que todos los alias de campo sean únicos. Recuerda que, si no se especifica ningún nombre, el nombre predeterminado es `{aggregation_function}_{field_name}`.
  </Accordion>
</AccordionGroup>

<div id="data-filtering-errors">
  ### Errores de filtrado de datos
</div>

<AccordionGroup>
  <Accordion title="Nombre de grupo no válido">
    **Error:** `invalid group name: GroupName`

    **Causa:** El nombre del grupo especificado no existe en tu organización.

    **Solución:**

    * Vuelve a comprobar la ortografía del nombre del grupo
    * Verifica que el grupo exista en Team Settings
    * Usa el nombre exacto del grupo tal como aparece en el panel de tu equipo
  </Accordion>

  <Accordion title="Formato de marca temporal no válido">
    **Error:** `invalid timestamp format`

    **Causa:** La marca temporal no tiene el formato RFC 3339 correcto.

    **Solución:** Usa el formato correcto de marca temporal:

    ```
    2023-01-01T00:00:00Z
    ```

    **Ejemplos válidos:**

    * `2024-01-01T00:00:00Z`
    * `2024-12-31T23:59:59Z`
    * `2024-06-15T12:30:45Z`
  </Accordion>

  <Accordion title="Filtros en conflicto">
    **Error:** `Cannot use both group_name and emails parameters`

    **Causa:** Se proporcionaron ambos parámetros, `group_name` y `emails`, en una solicitud de Cascade Analytics.

    **Solución:** Usa `group_name` O `emails`, pero no ambos:

    **No válido:**

    ```json theme={null}
    {
      "group_name": "engineering",
      "emails": ["user@example.com"]
    }
    ```

    **Válido:**

    ```json theme={null}
    {
      "group_name": "engineering"
    }
    ```

    **O bien:**

    ```json theme={null}
    {
      "emails": ["user@example.com", "user2@example.com"]
    }
    ```
  </Accordion>
</AccordionGroup>

<div id="rate-limiting">
  ## Límite de tasa
</div>

<AccordionGroup>
  <Accordion title="Se superó el límite de tasa">
    **Error:** `429 Too Many Requests`

    **Causa:** Has superado el límite de tasa de la API.

    **Solución:**

    * Espera antes de realizar más solicitudes
    * Implementa reintentos con espera exponencial en tu cliente
    * Considera agrupar varias consultas en una sola solicitud cuando sea posible
    * Ponte en contacto con soporte si necesitas límites de tasa más altos
  </Accordion>
</AccordionGroup>

<div id="debugging-tips">
  ## Consejos para depurar
</div>

<div id="1-start-simple">
  ### 1. Empieza con lo básico
</div>

Comienza con consultas básicas y agrega complejidad gradualmente:

```json theme={null}
{
  "service_key": "your_key",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}
```

<div id="2-validate-field-names">
  ### 2. Valida los nombres de los campos
</div>

Verifica los nombres de los campos en la documentación de [Campos disponibles](/es/desktop/accounts/api-reference/custom-analytics#available-fields).

<div id="3-check-aggregation-compatibility">
  ### 3. Verifica la compatibilidad de las agregaciones
</div>

Asegúrate de que las funciones de agregación sean compatibles con los tipos de campo que seleccionas.

<div id="4-test-filters-separately">
  ### 4. Prueba los filtros por separado
</div>

Si tu consulta no devuelve los resultados esperados, intenta quitar los filtros uno por uno para aislar el problema.

<div id="5-use-proper-json-formatting">
  ### 5. Usa el formato JSON correcto
</div>

Asegúrate de que tu JSON tenga el formato correcto y de que todas las cadenas estén entre comillas correctamente.

<div id="getting-help">
  ## Obtener ayuda
</div>

Si sigues teniendo problemas:

1. **Revisa atentamente el mensaje de error** - La mayoría de los errores incluyen indicaciones específicas sobre cómo resolver el problema
2. **Revisa los ejemplos** - Compara la estructura de tu consulta con los ejemplos de la documentación que funcionan
3. **Contacta con soporte** - Ponte en contacto con [Devin Desktop Support](https://windsurf.com/support) e incluye tu mensaje de error y la consulta específica

<div id="api-version-notes">
  ## Notas sobre versiones de la API
</div>

El manejo de errores y la validación han mejorado a partir de la versión 1.10.0 de la API. Si usas una versión anterior, considera actualizarla para obtener mensajes de error más detallados.