Manejo de errores

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

Invalid service key

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

Insufficient permissions

Error: Insufficient permissionsCause: La clave de servicio no tiene los permisos necesarios para el endpoint que estás utilizando.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 a tu solicitud de consulta:

"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]

data source no válido

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

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 de campos distintivos

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

Aliases 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 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

Invalid group name

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

Invalid timestamp format

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

Conflicting filters

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

{
  "emails": ["user@example.com", "user2@example.com"]
}

Limitación de tasa

Se superó el límite 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:

Revisa el mensaje de error con atención - La mayoría de los errores incluyen indicaciones específicas para solucionarlos
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 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.

Editor

Cascade

Cuentas

Conocimiento del contexto

Resolución de problemas

Seguridad

Descripción general

Formato de respuesta de error

Errores comunes

Errores de autenticación

Errores en la estructura de la consulta

Errores de campos y agregaciones

Errores de filtrado de datos

Limitación de tasa

Consejos para depurar

1. Comienza de forma sencilla

2. Validar nombres de campos

3. Verifica la compatibilidad de agregación

4. Prueba los filtros por separado

5. Usa un formato JSON adecuado

Obtén ayuda

Notas de la versión de la API