Manejo de errores

Descripción general

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.

Formato de la respuesta de error

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

{
  "error": "Error message describing what went wrong"
}

Errores comunes

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 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 para ver el permiso específico que requiere cada endpoint

Errores en la estructura de la consulta

Faltan selecciones

Error: at least one field or aggregation is requiredCausa: 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:

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

Fuente de datos no válida

Error: invalid query table: QUERY_DATA_SOURCE_UNSPECIFIEDCausa: 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

Funciones de agregación mezcladas

Error: all selection fields should have an aggregation function, or none of them shouldCausa: 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:

"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 agregación

Función de agregación no válida

Error: invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUMCause: La función de agregación no es compatible con el tipo de campo especificado.Solution: Consulta la sección Campos disponibles para ver qué funciones de agregación son válidas para cada campo. Los campos de tipo cadena normalmente solo admiten COUNT y UNSPECIFIED.

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:

"aggregations": [
  {
    "field": "distinct_developer_days",
    "name": "distinct_developer_days"
  }
]

Valid:

"aggregations": [
  {
    "field": "api_key",
    "name": "api_key"
  },
  {
    "field": "date",
    "name": "date"
  }
]

Alias de campo duplicados

Error: duplicate field alias for selection/aggregation: num_acceptancesCause: 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}.

Errores de filtrado de datos

Nombre de grupo no válido

Error: invalid group name: GroupNameCausa: 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

Formato de marca temporal no válido

Error: invalid timestamp formatCausa: 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

Filtros en conflicto

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:No válido:

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

Válido:

{
  "group_name": "engineering"
}

O bien:

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

Límite de tasa

Se superó el límite de tasa

Error: 429 Too Many RequestsCausa: 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

Consejos para depurar

Empieza con lo básico

Comienza con consultas básicas y agrega complejidad gradualmente:

{
  "service_key": "your_key",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}

Valida los nombres de los campos

Verifica los nombres de los campos en la documentación de Campos disponibles.

Verifica la compatibilidad de las agregaciones

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

Prueba los filtros por separado

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

Usa el formato JSON correcto

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

Obtener ayuda

Si sigues teniendo problemas:

Revisa atentamente el mensaje de error - La mayoría de los errores incluyen indicaciones específicas sobre cómo resolver el problema
Revisa los ejemplos - Compara la estructura de tu consulta con los ejemplos de la documentación que funcionan
Contacta con soporte - Ponte en contacto con Devin Desktop Support e incluye tu mensaje de error y la consulta específica

Notas sobre versiones de la API

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.

Devin Desktop

Centro de control de agentes

Versiones

Complementos de Windsurf

Cuentas

Seguridad

Descripción general

Formato de la respuesta de error

Errores comunes

Errores de autenticación

Errores en la estructura de la consulta

Errores de campos y agregación

Errores de filtrado de datos

Límite de tasa

Consejos para depurar

Empieza con lo básico

Valida los nombres de los campos

Verifica la compatibilidad de las agregaciones

Prueba los filtros por separado

Usa el formato JSON correcto

Obtener ayuda

Notas sobre versiones de la API

​Descripción general

​Formato de la respuesta de error

​Errores comunes

​Errores de autenticación

​Errores en la estructura de la consulta

​Errores de campos y agregación

​Errores de filtrado de datos

​Límite de tasa

​Consejos para depurar

​ Empieza con lo básico

​ Valida los nombres de los campos

​ Verifica la compatibilidad de las agregaciones

​ Prueba los filtros por separado

​ Usa el formato JSON correcto

​Obtener ayuda

​Notas sobre versiones de la API

Descripción general

Formato de la respuesta de error

Errores comunes

Errores de autenticación

Errores en la estructura de la consulta

Errores de campos y agregación

Errores de filtrado de datos

Límite de tasa

Consejos para depurar

Empieza con lo básico

Valida los nombres de los campos

Verifica la compatibilidad de las agregaciones

Prueba los filtros por separado

Usa el formato JSON correcto

Obtener ayuda

Notas sobre versiones de la API