Manejo de errores

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

Clave de servicio no válida

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

Permisos insuficientes

Error: Insufficient permissionsCause: La clave de servicio no tiene los permisos requeridos para el endpoint que estás llamando.Solution:

Actualiza los permisos de la clave de servicio en la configuración del equipo
Consulta la introducción a la API para ver el permiso específico que requiere cada endpoint

Errores en la estructura de la consulta

Faltan selections

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"
  }
]

data source inválida

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

Funciones de agregación mixtas

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

Función de agregación no válida

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.

Agregación en campos distinct

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"
  }
]

Alias de campo duplicados

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

Invalid group name

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

Invalid timestamp format

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

Conflicting filters

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

Límite de tasa superado

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:

Revisa cuidadosamente el mensaje de error - La mayoría de los errores incluyen indicaciones específicas sobre cómo resolverlo
Revisa los ejemplos - Compara la estructura de tu consulta con los ejemplos que funcionan en la documentación
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.

Primeros pasos

Funciones

Cascade (JetBrains)

Cuentas

Conocimiento de contexto

Mejores prácticas

Solución de problemas

Seguridad

Descripción general

Formato de respuesta de error

Errores frecuentes

Errores de autenticación

Errores en la estructura de la consulta

Errores de campos y agregaciones

Errores al filtrar datos

Limitación de tasa

Consejos para depurar

1. Empieza por lo básico

2. Validar los nombres de los campos

3. Verifica la compatibilidad de agregación

4. Prueba los filtros por separado

5. Usa un formato JSON adecuado

Obtener ayuda

Notas de la versión de la API