​
Descripción general

Analytics API devuelve mensajes de error detallados para ayudar a depurar consultas inválidas. Esta página cubre escenarios de error comunes y cómo resolverlos.

​
Formato de respuesta de error

Cuando se produce un error, la API devuelve una respuesta de error con un mensaje descriptivo: 
{
  "error": "Mensaje de error que describe qué salió mal"
}

​
Errores frecuentes

​
Errores de autenticación

Error: Invalid service keyCause: 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
Error: Insufficient permissionsCause: La clave de servicio no tiene los permisos requeridos “Teams Read-only”.Solution:
  • Actualiza los permisos de la clave de servicio en la configuración del equipo
  • Asegúrate de que la clave de servicio tenga acceso “Teams Read-only”

​
Errores en la estructura de la consulta

Error: at least one field or aggregation is requiredCausa: La solicitud de consulta no contiene ninguna selections ni aggregations.Solución: Agrega al menos una selección (selection) a tu solicitud de consulta:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]
Error: invalid query table: QUERY_DATA_SOURCE_UNSPECIFIEDCausa: Probablemente hay un error tipográfico en el campo data_source.Solución: Verifica la escritura de tu data source. Opciones válidas:
  • QUERY_DATA_SOURCE_USER_DATA
  • QUERY_DATA_SOURCE_CHAT_DATA
  • QUERY_DATA_SOURCE_COMMAND_DATA
  • QUERY_DATA_SOURCE_PCW_DATA
Error: all selection fields should have an aggregation function, or none of them shouldCausa: Algunas selections tienen funciones de agregación y otras no.Solución: Agrega funciones de agregación a todas las selections o elimínalas de todas:Inválido:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
  }
]
Válido:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]

​
Errores de campos y agregaciones

Error: invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUMCausa: La función de agregación no es compatible con el tipo de campo especificado.Solución: Consulta la sección Available Fields para ver qué funciones de agregación son válidas para cada campo. Los campos de tipo string normalmente solo admiten COUNT y UNSPECIFIED.
Error: tried to aggregate on a distinct field: distinct_developer_days. Consider aggregating on the non-distinct fields instead: [api_key date]Causa: Los campos con el patrón “distinct_*” no se pueden usar en la sección de aggregations.Solución: Usa los campos alternativos sugeridos para la agregación:No válido:
"aggregations": [
  {
    "field": "distinct_developer_days",
    "name": "distinct_developer_days"
  }
]
Válido:
"aggregations": [
  {
    "field": "api_key",
    "name": "api_key"
  },
  {
    "field": "date",
    "name": "date"
  }
]
Error: duplicate field alias for selection/aggregation: num_acceptancesCausa: Varias selections o aggregations tienen el mismo nombre.Solución: Asegúrate de que todos los alias de campo sean únicos. Recuerda que, si no se especifica un nombre, se usa por defecto {aggregation_function}_{field_name}.

​
Errores al filtrar datos

Error: invalid group name: GroupNameCausa: El nombre del grupo especificado no existe en tu organización.Solución:
  • Verifica la ortografía del nombre del grupo
  • Confirma que el grupo exista en la configuración de tu equipo
  • Usa el nombre del grupo exactamente como aparece en el panel de tu equipo
Error: invalid timestamp formatCausa: La marca de tiempo no está en el formato RFC 3339 correcto.Solución: Usa el formato de marca de tiempo correcto:
2023-01-01T00:00:00Z
Ejemplos válidos:
  • 2024-01-01T00:00:00Z
  • 2024-12-31T23:59:59Z
  • 2024-06-15T12:30:45Z
Error: Cannot use both group_name and emails parametersCausa: 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:Inválido:
{
  "group_name": "engineering",
  "emails": ["user@example.com"]
}
Válido:
{
  "group_name": "engineering"
}
O bien:
{
  "emails": ["user@example.com", "user2@example.com"]
}

​
Limitación de tasa

Error: 429 Too Many RequestsCausa: Has excedido el límite de solicitudes de la API.Solución:
  • Espera antes de realizar solicitudes adicionales
  • Implementa un backoff exponencial en tu cliente
  • Considera agrupar varias consultas en una sola solicitud cuando sea posible
  • Contacta al soporte si necesitas límites de tasa más altos

​
Consejos para depurar

​
1. Empieza por lo básico

Comienza con consultas simples y ve añadiendo complejidad gradualmente: 
{
  "service_key": "your_key",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}

​
2. Validar los nombres de los campos

Verifica los nombres de los campos con la documentación de Available Fields.

​
3. Verifica la compatibilidad de agregación

Asegúrate de que tus funciones de agregación sean compatibles con los tipos de campo que estás seleccionando.

​
4. Prueba los filtros por separado

Si la consulta no arroja los resultados esperados, prueba a quitar los filtros uno por uno para aislar el problema.

​
5. Usa un formato JSON adecuado

Asegúrate de que tu JSON esté bien formateado y de que todas las cadenas estén correctamente entrecomilladas.

​
Obtener ayuda

Si sigues teniendo problemas:
  1. Revisa cuidadosamente el mensaje de error - La mayoría de los errores incluyen indicaciones específicas sobre cómo resolverlo
  2. Revisa los ejemplos - Compara la estructura de tu consulta con los ejemplos que funcionan en la documentación
  3. Contacta al soporte - Ponte en contacto con Windsurf Support y envía tu mensaje de error específico junto con tu consulta

​
Notas de la versión de la API

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