​
Descripción general

La Analytics API devuelve mensajes de error detallados para ayudar a depurar consultas no válidas. Esta página aborda 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 comunes

​
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 necesarios de “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 a tu solicitud de consulta:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]
Error: invalid query table: QUERY_DATA_SOURCE_UNSPECIFIEDCausa: Probablemente haya un error tipográfico en el campo data_source.Solución: Verifica la ortografía 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:Invá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 aliases de campos sean únicos. Recuerda que, si no se especifica un nombre, el valor predeterminado es {aggregation_function}_{field_name}.

​
Errores de filtrado de datos

Error: invalid group name: GroupNameCausa: El nombre del grupo especificado no existe en tu organización.Solución:
  • Verifica la escritura del nombre del grupo
  • Comprueba que el grupo exista en la configuración de tu equipo
  • Usa el nombre exacto del grupo tal 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 correcto de marca de tiempo:
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 los 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:
{
  "emails": ["user@example.com", "user2@example.com"]
}

​
Limitación de tasa

Error: 429 Too Many RequestsCausa: Superaste el límite de tasa de la API.Solución:
  • Espera antes de realizar más solicitudes
  • Implementa retroceso exponencial (exponential backoff) 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

​
Consejos para depurar

​
1. Comienza de forma sencilla

Empieza con consultas básicas 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 nombres de campos

Vuelve a comprobar 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 tu consulta no devuelve los resultados esperados, prueba a eliminar 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 que todas las cadenas estén correctamente entrecomilladas.

​
Obtén ayuda

Si sigues teniendo problemas:
  1. Revisa el mensaje de error con atención - La mayoría de los errores incluyen indicaciones específicas para solucionarlos
  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 y la consulta específicos

​
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 estás usando una versión anterior, considera actualizar para obtener mensajes de error más detallados.