Overview
This guide covers common issues when using Consuelo for internal operations and how to resolve them.API Issues
401 Unauthorized
Cause: Invalid or expired API key Solutions:- Check API key in Settings → APIs & Webhooks
- Verify key hasn’t expired
- Regenerate if needed
- Update scripts with new key
429 Rate Limited
Cause: Too many requests per minute Solutions:- Reduce batch size
- Add delays between requests (1 second recommended)
- Implement exponential backoff
- Consider using batch operations
Query Timeout
Cause: Complex query or large dataset Solutions:- Add filters to narrow results
- Use pagination (first/after)
- Simplify query
- Break into multiple queries
Workflow Issues
Workflow Not Triggering
| Check | Solution |
|---|---|
| Workflow inactive | Toggle to Active |
| Wrong trigger conditions | Review trigger settings |
| Filter blocking | Check filter logic |
| API permissions | Verify key has access |
Workflow Runs Failing
Check workflow runs:- Go to Settings → Workflows → [Your Workflow]
- Click Runs tab
- Review error messages
- Check which step failed
- Search returned empty: Add filter to handle no results
- Record not found: Verify record ID exists
- Permission denied: Check API key permissions
- Validation error: Check field values
Iterator Not Closing
Cause: Iterator not properly configured Solution:- Ensure all branches inside iterator end properly
- Close iterator after processing
- Check for infinite loops
Dashboard Issues
Widget Not Loading
| Check | Solution |
|---|---|
| Beta feature enabled | Settings → Updates → Early Access |
| Data exists | Verify records match filter |
| Filter too restrictive | Broaden filter criteria |
| Max bars exceeded | Group by larger time period |
iFrame Not Displaying
Cause: External site blocks embedding Solutions:- Check X-Frame-Options header
- Use public/shared links
- Verify HTTPS URLs
- Check CSP settings
Data Issues
Duplicates Not Detected
Cause: Matching criteria too strict Solutions:- Use email matching (most reliable)
- Normalize data before comparison
- Consider fuzzy matching
- Review false positives
Cleanup Deleted Wrong Records
Prevention:- Always archive, never delete
- Test on small subset first
- Review before bulk operations
- Maintain audit logs
- Restore from backup
- Re-create from source
- Contact admin if critical
Email Issues
Emails Not Sending
| Check | Solution |
|---|---|
| Email account connected | Settings → Accounts |
| Sending enabled | Check account permissions |
| Recipient valid | Verify email format |
| Rate limit hit | Check quota in settings |
Single Recipient Limit
Workaround for multiple recipients:- Create distribution list email
- Use separate Send Email actions
- Consider Slack notification instead
Rate Limiting
API Rate Limits
| Limit | Value |
|---|---|
| Requests per minute | 100 |
| Batch size | 60 records |
| Delay recommended | 1000ms between calls |
Best Practices
- Use batch operations
- Add delays in loops
- Cache results when possible
- Monitor usage in Settings
Getting Help
Resources
- Documentation: docs.consuelohq.com
- Internal Slack: #consuelo-support
- Workflow runs: Check error logs
- API playground: Test queries directly
Information to Include
When reporting issues:- Workflow ID or API endpoint
- Error message (exact text)
- Time of occurrence
- Steps to reproduce
- Expected vs actual behavior