Skip to main content

​
Troubleshooting Guide

Quick solutions to the most common issues you might encounter while integrating with Plati AI.
Quick Debug Tip: Always check with your Plati AI team first - they can help identify what went wrong.

​
Authentication Issues

Error Message: {"message": "User not authenticated"}Common Causes:
  • API key is incorrect or expired
  • Missing Bearer prefix in Authorization header
  • API key doesn’t have sufficient permissions
Solutions:
curl -X GET https://api.plati.ai/workers \
  -H "Authorization: Bearer YOUR_ACTUAL_API_KEY"
Quick Fix:
  1. Contact your Plati AI team
  2. Generate a new API key with read-write permissions
  3. Update your code with the new key
Error Message: {"message": "User does not have access to workspace"}Cause: Your API key has read-only permissions but you’re trying to create/modify resources.Solution: Create a new API key with read-write permissions.

​
Assistant Creation Issues

Error Message:
{
  "error": "Validation Error",
  "details": [{
    "path": ["languages"],
    "message": "Languages must be in format 'xx' or 'xx-XX'"
  }]
}
Common Mistakes:
// ❌ Wrong formats
"languages": ["english", "portuguese", "EN", "pt_br"]

// ✅ Correct formats  
"languages": ["en", "pt", "en-US", "pt-BR"]
Valid Language Codes:
  • en (English)
  • pt (Portuguese)
  • es (Spanish)
  • en-US (US English)
  • pt-BR (Brazilian Portuguese)
  • es-ES (Spain Spanish)
Error Message: {"message": "Worker not found"}Causes:
  • Worker ID is incorrect
  • Worker belongs to different workspace
  • Worker was deleted
Debug Steps:
curl -X GET https://api.plati.ai/workers \
  -H "Authorization: Bearer YOUR_API_KEY"

​
WhatsApp Integration Issues

Symptoms:
  • Messages sent to WhatsApp number but no webhook calls
  • Verification works but no message events
Debug Checklist:
1

Check Webhook Configuration

In WhatsApp Business Manager:
  • Callback URL matches exactly what Plati AI provided
  • Verify token matches exactly (case-sensitive)
  • Subscribed to messages field
2

Test Webhook URL

# Test if your webhook URL is accessible
curl -I YOUR_WEBHOOK_URL
# Should return 200 OK
3

Check SSL Certificate

WhatsApp requires valid SSL. Test at: https://www.ssllabs.com/ssltest/
4

Verify Business Account

  • WhatsApp Business Account is verified
  • Phone number is active and verified
  • No restrictions on the account
Common Solutions:
  • Use ngrok for local development: ngrok http 3000
  • Ensure webhook URL uses HTTPS (required by WhatsApp)
  • Check firewall settings blocking WhatsApp IPs
Error Message: {"error": "Template not found or not approved"}Common Issues:

Template Status

Templates need 24-48 hours for WhatsApp approval

Exact Name Match

Template name must match exactly (case-sensitive)

Component Mismatch

Components must match approved template structure

Language Code

Use correct language codes (en_US, pt_BR, etc.)
Debug Template Status:
# Check all templates for a channel
curl -X GET https://api.plati.ai/channels/CHANNEL_ID/waba/templates \
  -H "Authorization: Bearer YOUR_API_KEY"
Error Message: {"error": "Rate limit exceeded"}WhatsApp Rate Limits:
  • 1,000 messages per second per phone number
  • 24-hour message window for business-initiated messages
  • Template message limits based on phone number tier
Solutions:
  • Implement exponential backoff in your code
  • Queue messages and send at appropriate intervals
  • Request higher tier status from WhatsApp
  • Use conversation-based messaging instead of templates when possible

​
Conversation Flow Issues

Symptoms:
  • Messages received but no AI response
  • Partial responses or errors in logs
Debug Steps:
1

Check Assistant Configuration

# Verify assistant exists and is configured
response = requests.get(
    f"https://api.plati.ai/assistant/{assistant_id}",
    headers={"Authorization": f"Bearer {api_key}"}
)

assistant = response.json()["data"]
print(f"Assistant Status: {assistant.get('status')}")
print(f"Model: {assistant.get('model')}")
print(f"Provider: {assistant.get('provider')}")
2

Verify Channel Connection

# Check if assistant is properly connected to channel
response = requests.get(
    f"https://api.plati.ai/channels/{channel_id}",
    headers={"Authorization": f"Bearer {api_key}"}
)

channel = response.json()["data"]
print(f"Channel Active: {channel.get('active')}")
3

Check Conversation Logs

Contact your Plati AI team and check:
  • Are messages being received?
  • Any error messages in the logs?
  • Assistant response attempts?
Symptoms:
  • Assistant doesn’t remember previous messages
  • Conversations seem to start fresh each time
Causes & Solutions:

Identity Issues

Problem: Different identity for each message Solution: Use consistent phone/email to identify users

Memory Settings

Problem: Memory disabled or limited Solution: Check memory configuration in assistant settings

Session Timeout

Problem: Long gaps between messages Solution: Adjust session timeout settings

Channel Switching

Problem: User switching between channels Solution: Ensure identity linking across channels

​
Performance Issues

Causes:
  • Large conversation history
  • Complex instructions
  • Model provider latency
  • Network issues
Optimization Tips:
1

Optimize Instructions

{
  "instructions": "Be concise and helpful. Respond in under 50 words when possible."
}
2

Adjust Model Settings

{
  "configs": {
    "temperature": 0.3,
    "max_token_limit": 150
  }
}
3

Monitor Performance

Contact your Plati AI team to check response times.
Symptoms:
  • Unexpected API costs
  • Rate limits being hit
  • Too many requests
Common Causes:
  • Polling instead of using webhooks
  • Redundant API calls
  • Not caching responses
  • Inefficient conversation flows
Optimization:
# ❌ Don't poll for new messages
while True:
    messages = get_new_messages()
    time.sleep(1)

# ✅ Use webhooks instead
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    # Process incoming messages
    pass

​
Common Error Codes

​
400 Bad Request
object
Cause: Invalid request format or missing required fields Solution: Check request body against API documentation
​
401 Unauthorized
object
Cause: Missing or invalid API key Solution: Check authorization header format
​
403 Forbidden
object
Cause: Insufficient permissions Solution: Use API key with appropriate permissions
​
404 Not Found
object
Cause: Resource doesn’t exist or wrong endpoint Solution: Verify resource IDs and endpoint URLs
​
422 Validation Error
object
Cause: Request body fails validation Solution: Check the details array in response for specific validation errors
​
429 Rate Limited
object
Cause: Too many requests Solution: Implement exponential backoff and respect rate limits
​
500 Internal Server Error
object
Cause: Server-side issue Solution: Check status page and contact support if persistent

​
Getting Help

Check System Status

See if there are any ongoing issues or maintenance

Contact Support

Get help from our technical support team

LinkedIn Community

Connect with Plati AI team and updates

​
Debug Checklist

Before reaching out for help, please check:
1

Basic Connectivity

  • API key is valid and has correct permissions
  • Endpoints are reachable
  • Request format matches documentation
2

Resource Configuration

  • Worker/Assistant is properly configured
  • Channels are connected and active
  • Identities are correctly linked
3

Integration-Specific

  • WhatsApp webhook is configured correctly
  • Templates are approved (if using WhatsApp)
  • SSL certificates are valid
4

Logs and Monitoring

  • Check dashboard logs for errors
  • Verify conversation flow in dashboard
  • Monitor response times and success rates
Pro Tip: Include relevant log snippets, error messages, and your configuration when asking for help. This helps us assist you much faster!