telegram-management-system/marketing-agent/docs/api/TROUBLESHOOTING.md

API Troubleshooting Guide

This guide helps you diagnose and resolve common issues with the Telegram Marketing Agent API.

Table of Contents

• Authentication Issues
• Rate Limiting
• Campaign Execution Problems
• Data Import/Export Issues
• Webhook Problems
• Performance Issues
• Error Codes Reference

Authentication Issues

Problem: 401 Unauthorized Error

Symptoms:

{
  "success": false,
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

Solutions:

1. Check Token Format

   # Correct format
   curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/v1/users
   
   # Common mistakes
   curl -H "Authorization: YOUR_TOKEN" # Missing "Bearer" prefix
   curl -H "Authorization: bearer YOUR_TOKEN" # Lowercase "bearer"
   

2. Verify Token Expiration

   • Access tokens expire after 24 hours
   • Use the refresh token endpoint to get a new access token

   curl -X POST https://api.example.com/v1/auth/refresh \
     -H "Content-Type: application/json" \
     -d '{"refreshToken": "YOUR_REFRESH_TOKEN"}'
   

3. Check API Key (if using)

   curl -H "X-API-Key: YOUR_API_KEY" https://api.example.com/v1/users
   

Problem: 403 Forbidden Error

Symptoms:

• User authenticated but lacks permissions
• Specific endpoints return forbidden

Solutions:

1. Check user role and permissions
2. Verify endpoint access requirements
3. Contact admin for permission updates

Rate Limiting

Problem: 429 Too Many Requests

Symptoms:

{
  "success": false,
  "error": "Too many requests",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "retryAfter": 60
  }
}

Solutions:

1. Check Rate Limit Headers

   X-RateLimit-Limit: 100
   X-RateLimit-Remaining: 0
   X-RateLimit-Reset: 1642012800
   

2. Implement Exponential Backoff

   async function retryWithBackoff(fn, maxRetries = 3) {
     for (let i = 0; i < maxRetries; i++) {
       try {
         return await fn();
       } catch (error) {
         if (error.status === 429 && i < maxRetries - 1) {
           const delay = Math.pow(2, i) * 1000;
           await new Promise(resolve => setTimeout(resolve, delay));
         } else {
           throw error;
         }
       }
     }
   }
   

3. Batch Operations

   • Use bulk endpoints when available
   • Group multiple operations into single requests

Campaign Execution Problems

Problem: Campaign Fails to Execute

Symptoms:

• Campaign status remains "draft"
• Execution endpoint returns errors

Solutions:

1. Validate Campaign Configuration

   # Check campaign details
   curl -X GET https://api.example.com/v1/orchestrator/campaigns/CAMPAIGN_ID \
     -H "Authorization: Bearer YOUR_TOKEN"
   

2. Common Issues:

   • Empty target audience
   • Missing message content
   • Invalid scheduling parameters
   • Telegram account not connected

3. Test Mode First

   curl -X POST https://api.example.com/v1/orchestrator/campaigns/CAMPAIGN_ID/execute \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "test": true,
       "testUsers": ["user_123", "user_456"]
     }'
   

Problem: Low Delivery Rate

Solutions:

1. Check Rate Limits

   • Telegram has strict rate limits
   • Reduce messages per second in campaign settings

2. Verify User Status

   • Check if users have blocked the bot
   • Ensure phone numbers are valid

3. Monitor Telegram Account Health

   • Check for account restrictions
   • Verify account connection status

Data Import/Export Issues

Problem: Import Fails with Validation Errors

Solutions:

1. Validate CSV Format

   telegramId,username,firstName,lastName,phoneNumber,tags
   123456789,johndoe,John,Doe,+1234567890,"customer,active"
   

2. Common Issues:

   • Missing required fields
   • Invalid phone number format
   • Special characters in CSV
   • File encoding (use UTF-8)

3. Use Template

   # Download template
   curl -X GET https://api.example.com/v1/users/import/template \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -o user_template.csv
   

Problem: Export Timeout for Large Datasets

Solutions:

1. Use Filters

   {
     "format": "csv",
     "filters": {
       "status": "active",
       "createdAt": {
         "from": "2024-01-01",
         "to": "2024-01-31"
       }
     },
     "limit": 10000
   }
   

2. Paginated Export

   • Export in batches
   • Use background job for large exports

Webhook Problems

Problem: Webhooks Not Triggering

Solutions:

1. Verify Webhook Configuration

   curl -X GET https://api.example.com/v1/webhooks/WEBHOOK_ID \
     -H "Authorization: Bearer YOUR_TOKEN"
   

2. Test Webhook

   curl -X POST https://api.example.com/v1/webhooks/WEBHOOK_ID/test \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "event": "campaign.completed",
       "payload": {"test": true}
     }'
   

3. Common Issues:

   • URL not publicly accessible
   • SSL certificate problems
   • Timeout (webhook must respond within 10s)
   • Response status not 2xx

Problem: Duplicate Webhook Events

Solutions:

1. Implement idempotency using event IDs
2. Check webhook logs for retry attempts
3. Ensure webhook responds quickly

Performance Issues

Problem: Slow API Response Times

Solutions:

1. Use Caching Headers

   # Check if response is cached
   curl -I https://api.example.com/v1/analytics/dashboard \
     -H "Authorization: Bearer YOUR_TOKEN"
   

2. Optimize Queries

   • Use specific field selection
   • Implement pagination
   • Add appropriate filters

3. Batch Operations

   {
     "operations": [
       {"method": "GET", "path": "/users/user_123"},
       {"method": "GET", "path": "/users/user_456"}
     ]
   }
   

Problem: Timeout Errors

Solutions:

1. Increase Client Timeout

   const response = await fetch(url, {
     timeout: 30000 // 30 seconds
   });
   

2. Use Async Operations

   • For long-running tasks, use job queues
   • Poll for results

Error Codes Reference

HTTP Status Codes

Code	Meaning	Common Causes
400	Bad Request	Invalid parameters, malformed JSON
401	Unauthorized	Missing/invalid token, expired token
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate resource, conflicting state
422	Unprocessable Entity	Validation errors
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side issue
502	Bad Gateway	Service unavailable
503	Service Unavailable	Maintenance, overload

Application Error Codes

Code	Description	Solution
AUTH_FAILED	Authentication failed	Check credentials
TOKEN_EXPIRED	Access token expired	Refresh token
INVALID_INPUT	Input validation failed	Check request body
RESOURCE_NOT_FOUND	Requested resource not found	Verify ID/path
DUPLICATE_RESOURCE	Resource already exists	Use update instead
CAMPAIGN_NOT_READY	Campaign missing required data	Complete campaign setup
TELEGRAM_ERROR	Telegram API error	Check account status
QUOTA_EXCEEDED	Account quota exceeded	Upgrade plan

Debug Mode

Enable debug mode for detailed error information:

curl -X GET https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Debug-Mode: true"

Getting Help

If you're still experiencing issues:

1. Check Logs

   • Request ID in response headers
   • Include in support tickets

2. API Status

   • Check https://status.example.com
   • Follow @api_status for updates

3. Support Channels

   • Email: api-support@example.com
   • Discord: https://discord.gg/example
   • GitHub Issues: https://github.com/example/api/issues

Best Practices

1. Always Handle Errors

   try {
     const response = await api.createCampaign(data);
   } catch (error) {
     if (error.code === 'RATE_LIMIT_EXCEEDED') {
       // Handle rate limit
     } else if (error.code === 'VALIDATION_ERROR') {
       // Handle validation errors
     } else {
       // Handle other errors
     }
   }
   

2. Log Everything

   • Request/response bodies
   • Headers
   • Timestamps
   • Error messages

3. Monitor Your Integration

   • Set up alerts for failures
   • Track success rates
   • Monitor response times

4. Use SDK When Available

   • Automatic retry logic
   • Built-in error handling
   • Type safety