Analytics API Reference
Error Handling
Common error messages and debugging tips for the Analytics API
Overview
The Analytics API returns detailed error messages to help debug invalid queries. This page covers common error scenarios and how to resolve them.Error Response Format
When an error occurs, the API returns an error response with a descriptive message:Common Errors
Authentication Errors
Invalid service key
Invalid service key
Error:
Invalid service keyCause: The provided service key is not valid or has been revoked.Solution:- Verify your service key is correct
- Check that the service key hasn’t been revoked
- Generate a new service key if needed
Insufficient permissions
Insufficient permissions
Error:
Insufficient permissionsCause: The service key doesn’t have the required “Teams Read-only” permissions.Solution:- Update the service key permissions in team settings
- Ensure the service key has “Teams Read-only” access
Query Structure Errors
Missing selections
Missing selections
Error:
at least one field or aggregation is requiredCause: The query request doesn’t contain any selections or aggregations.Solution: Add at least one selection to your query request:Invalid data source
Invalid data source
Error:
invalid query table: QUERY_DATA_SOURCE_UNSPECIFIEDCause: There’s likely a typo in the data_source field.Solution: Double-check the spelling of your data source. Valid options:QUERY_DATA_SOURCE_USER_DATAQUERY_DATA_SOURCE_CHAT_DATAQUERY_DATA_SOURCE_COMMAND_DATAQUERY_DATA_SOURCE_PCW_DATA
Mixed aggregation functions
Mixed aggregation functions
Error: Valid:
all selection fields should have an aggregation function, or none of them shouldCause: Some selections have aggregation functions while others don’t.Solution: Either add aggregation functions to all selections or remove them from all:Invalid:Field and Aggregation Errors
Invalid aggregation function
Invalid aggregation function
Error:
invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUMCause: The aggregation function is not supported for the specified field type.Solution: Check the Available Fields section to see which aggregation functions are valid for each field. String fields typically only support COUNT and UNSPECIFIED.Distinct field aggregation
Distinct field aggregation
Error: Valid:
tried to aggregate on a distinct field: distinct_developer_days. Consider aggregating on the non-distinct fields instead: [api_key date]Cause: Fields with the “distinct_*” pattern cannot be used in the aggregations section.Solution: Use the suggested alternative fields for aggregation:Invalid:Duplicate field aliases
Duplicate field aliases
Error:
duplicate field alias for selection/aggregation: num_acceptancesCause: Multiple selections or aggregations have the same name.Solution: Ensure all field aliases are unique. Remember that if no name is specified, it defaults to {aggregation_function}_{field_name}.Data Filtering Errors
Invalid group name
Invalid group name
Error:
invalid group name: GroupNameCause: The specified group name doesn’t exist in your organization.Solution:- Double-check the group name spelling
- Verify the group exists in your team settings
- Use the exact group name as it appears in your team dashboard
Invalid timestamp format
Invalid timestamp format
Error: Valid examples:
invalid timestamp formatCause: The timestamp is not in the correct RFC 3339 format.Solution: Use the correct timestamp format:2024-01-01T00:00:00Z2024-12-31T23:59:59Z2024-06-15T12:30:45Z
Conflicting filters
Conflicting filters
Error: Valid:Or:
Cannot use both group_name and emails parametersCause: Both group_name and emails parameters were provided in a Cascade Analytics request.Solution: Use either group_name OR emails, but not both:Invalid:Rate Limiting
Rate limit exceeded
Rate limit exceeded
Error:
429 Too Many RequestsCause: You’ve exceeded the API rate limit.Solution:- Wait before making additional requests
- Implement exponential backoff in your client
- Consider batching multiple queries into single requests where possible
- Contact support if you need higher rate limits
Debugging Tips
1. Start Simple
Begin with basic queries and gradually add complexity:2. Validate Field Names
Double-check field names against the Available Fields documentation.3. Check Aggregation Compatibility
Ensure your aggregation functions are compatible with the field types you’re selecting.4. Test Filters Separately
If your query isn’t returning expected results, try removing filters one by one to isolate the issue.5. Use Proper JSON Formatting
Ensure your JSON is properly formatted and all strings are quoted correctly.Getting Help
If you continue to experience issues:- Check the error message carefully - Most errors include specific guidance on how to fix the issue
- Review the examples - Compare your query structure to the working examples in the documentation
- Contact support - Reach out to Windsurf Support with your specific error message and query