Comprehensive Issue Resolution
Common Issues and Solutions
Authentication & Authorization Problems
API Token Authentication Errors
API Token Authentication Errors
- Missing subdomain: Ensure you’re using the correct subdomain in the URL
- Invalid token format: API tokens should not include “Bearer ” prefix
- Wrong header name: Use
x-api-token
orAuthorization
(without “Bearer ”) - Expired token: Generate a new token from the admin dashboard
- Wrong environment: Verify you’re calling the correct environment (dev/staging/production)
"Unauthorized"
- Token missing or invalid format"Organisation ID not found in API token"
- Token doesn’t contain valid org data"User ID not found in API token"
- Token doesn’t contain valid user data"Organisation not found"
- Wrong subdomain or org doesn’t exist
Subdomain Configuration Issues
Subdomain Configuration Issues
- Missing subdomain: API calls must include your organization’s subdomain
- Wrong subdomain: Verify subdomain matches your organization exactly
- Environment mismatch: Ensure you’re using the right environment subdomain
- Development:
{subdomain}.devadmin.nudj.cx
- Staging:
{subdomain}.stgadmin.nudj.cx
- Production:
{subdomain}.nudj.cx
- Development:
- Verify your subdomain in the admin dashboard
- Check API tokens are generated for the correct organization
- Test with curl first to isolate issues
- Ensure DNS resolution is working for your subdomain
Session & Cookie Authentication
Session & Cookie Authentication
API Error Responses
HTTP Error Codes
HTTP Error Codes
Validation Errors
Validation Errors
- Required fields missing: Check all required parameters are included
- Invalid data types: Ensure numbers are numbers, strings are strings
- Enum values: Use exact values from API documentation
- String length: Check minimum/maximum length requirements
- Format validation: Verify email, URL, and date formats
Rate Limiting
Rate Limiting
X-RateLimit-Limit
, X-RateLimit-Remaining
, X-RateLimit-Reset
) for current enforced values.- Integration API: ~100 requests per minute
- Admin API: ~200 requests per minute
- Analytics API: ~50 requests per minute
- Implement exponential backoff
- Cache responses when appropriate
- Use batch endpoints when available
- Monitor rate limit headers
Challenge & Gamification Issues
Challenge Completion Problems
Challenge Completion Problems
- Eligibility rules: User doesn’t meet challenge requirements
- Challenge status: Challenge is not live or has expired
- Action completion: Not all required actions completed
- Timing issues: Actions completed outside challenge window
- Community access: User not member of required community
- Verify challenge is live and within date range
- Check user meets all eligibility requirements
- Confirm all required actions are completed
- Review action participation timestamps
- Validate community membership status
Action Participation Errors
Action Participation Errors
- Invalid response format: Response doesn’t match action requirements
- Duplicate submissions: Action already completed by user
- Action not found: Invalid actionId provided
- Challenge not active: Associated challenge is not live
- Authentication issues: User token invalid or expired
- Quiz: Requires
selectedAnswerId
oranswers
array - Prediction: Requires
prediction
value and optionalconfidence
- Social: May require external verification
- Video: Requires viewing time and progress data
- Custom: Check specific action requirements
Points & XP Calculation Issues
Points & XP Calculation Issues
- Delayed calculation: Points may take time to process
- Multiplier errors: Community or user multipliers not applied
- Streak interruption: Daily streak broken affecting bonuses
- Event timing: Points calculated based on action completion time
- Rounding errors: Floating point precision in calculations
- Check base points configuration for action
- Verify active multipliers and bonuses
- Confirm streak status and requirements
- Review event timestamps and timing rules
- Test with small point values to isolate issues
Reward & Commerce Issues
Reward Redemption Failures
Reward Redemption Failures
- Insufficient points: User doesn’t have enough points
- Reward unavailable: Reward is sold out or expired
- Eligibility requirements: User doesn’t meet reward criteria
- Geographic restrictions: Reward not available in user’s region
- Stock limitations: Reward has limited quantity available
- Check user’s current point balance
- Verify reward is active and in stock
- Confirm user meets eligibility requirements
- Review geographic and temporal restrictions
- Test redemption flow with admin privileges
Reward Entry & Distribution Issues
Reward Entry & Distribution Issues
- Entry not recorded: Purchase/entry not properly recorded
- Draw delays: Automatic draws not processing on time
- Winner notification: Users not receiving winner notifications
- Fulfillment delays: Physical rewards not being shipped
- Status updates: Entry status not updating properly
- Verify entry was recorded in system
- Check draw configuration and timing
- Review winner selection algorithm
- Confirm notification system is working
- Validate fulfillment partner integration
Integration & Performance Issues
API Performance Problems
API Performance Problems
- Use pagination: Limit large data sets with
limit
andskip
- Implement caching: Cache frequently accessed data
- Optimize queries: Use specific field selection where available
- Batch requests: Combine multiple operations when possible
- Monitor response times: Set up alerts for slow responses
Data Synchronization Issues
Data Synchronization Issues
- Cache staleness: Cached data not updating properly
- Race conditions: Concurrent updates causing conflicts
- Event processing delays: Events not processed in order
- Database replication lag: Read replicas behind master
- Client state management: Frontend state out of sync
- Implement proper cache invalidation
- Use optimistic updates with rollback
- Handle race conditions gracefully
- Set appropriate cache TTL values
- Use real-time updates where needed
Third-Party Integration Problems
Third-Party Integration Problems
- OAuth token expiry: Social media tokens need refresh
- API changes: Third-party APIs change breaking integration
- Rate limiting: External service rate limits exceeded
- Authentication failures: Invalid or expired credentials
- Service outages: Third-party service temporarily unavailable
- YouTube: Channel data, video interactions
- Instagram: Profile data, post engagement
- Spotify: Listening data, playlist interactions
- Google: Authentication, profile data
- Custom webhooks: Bidirectional data sync
Debugging Tools and Techniques
API Testing & Inspection
Log Analysis
Error Recovery Strategies
Retry Logic Implementation
Graceful Error Handling
Performance Monitoring
API Response Time Tracking
Getting Help & Support
Before Contacting Support
Check System Status
Review Documentation
Test with curl
Gather Debug Information
Support Channels
Technical Support
API Status
Documentation
GitHub Issues
Information to Include When Reporting Issues
When contacting support, please provide:Environment Information
Environment Information
- Organization subdomain
- API endpoint being called
- Environment (development/staging/production)
- Timestamp of the issue
- Browser/client information if applicable
Error Details
Error Details
- Complete error message and stack trace
- HTTP status codes and response bodies
- Request payload and headers (remove sensitive data)
- Steps to reproduce the issue
Debug Information
Debug Information
Self-Service Debug Checklist
Verify Authentication
- API token is valid and not expired
- Correct subdomain in API URLs
- Proper header format (
x-api-token
orAuthorization
) - Token has required permissions for endpoint
Check Request Format
- URL structure matches API documentation
- Request method (GET/POST/PUT/DELETE) is correct
- Content-Type header is set to
application/json
- Request body is valid JSON (for POST/PUT requests)
- All required parameters are included
Test Network Connectivity
- Can reach the API subdomain (ping test)
- No firewall blocking HTTPS traffic
- DNS resolution working correctly
- SSL certificate is valid
Review Response Handling
- Parsing JSON responses correctly
- Handling error responses appropriately
- Checking HTTP status codes
- Following pagination for large data sets
Monitor Rate Limits
- Not exceeding API rate limits
- Implementing retry logic with backoff
- Caching responses where appropriate
- Using batch endpoints when available
Quick Reference
Common Error Codes
Code | Description | Common Causes | Solutions |
---|---|---|---|
400 | Bad Request | Invalid input, missing required fields | Check request format and required parameters |
401 | Unauthorized | Invalid/missing API token | Verify token and authentication headers |
403 | Forbidden | Insufficient permissions | Check user roles and API permissions |
404 | Not Found | Resource doesn’t exist | Verify IDs and endpoint URLs |
429 | Rate Limited | Too many requests | Implement backoff and retry logic |
500 | Server Error | Internal platform issue | Check status page, retry with backoff |
API Rate Limits
X-RateLimit-Limit
, X-RateLimit-Remaining
, X-RateLimit-Reset
) for current enforced values.API | Requests per Minute (Approximate) | Burst Limit (Approximate) |
---|---|---|
Integration API | 100 | 200 |
Admin API | 200 | 400 |
Analytics API | 50 | 100 |