Troubleshooting Guide

Common issues and solutions when integrating with the Chinqit SMS Gateway API.

🔍 General Troubleshooting Steps

1. Verify API Key: Ensure your API key is correct and active
2. Check Request Format: Verify your request body matches the API specification
3. Review Error Messages: Check the error response for specific details
4. Test Connectivity: Ensure your application can reach https://sms.chinqit.com

🔐 Authentication Issues

401 Unauthorized - Missing API Key

Symptoms:

• 401 status code
• "API key is required" error message

Solutions:

1. Verify Header Name

   # Must be exactly: X-API-Key (case-sensitive)
   curl -H "X-API-Key: your-key" https://sms.chinqit.com/messages/send

2. Check Header Format

   // Correct
   headers: {
     'X-API-Key': 'your-api-key'
   }
   
   // Incorrect - missing hyphen
   headers: {
     'X_API_Key': 'your-api-key'
   }

3. Verify API Key is Included

   • Check that your API key is being sent in every request
   • Ensure no middleware is stripping the header

403 Forbidden - Invalid API Key

Symptoms:

• 403 status code
• "Invalid API key" error message

Solutions:

1. Verify API Key

   • Contact Chinqit support to confirm your API key is active
   • Check for typos or extra spaces in your API key
   • Ensure you're using the correct API key for your environment

2. Check API Key Format

   # Ensure no extra spaces or characters
   # Correct: "abc123xyz"
   # Incorrect: " abc123xyz " or "abc123xyz\n"

3. Regenerate API Key

   • If your API key has been compromised or rotated, request a new one from Chinqit

📝 Validation Errors

400 Bad Request - Validation Error

Symptoms:

• 400 status code
• "Validation failed" message with error details

Common Validation Errors:

Missing Required Field:

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "path": ["phoneNumber"],
      "message": "Required"
    }
  ]
}

Invalid Phone Number Format:

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "path": ["phoneNumber"],
      "message": "Invalid phone number format"
    }
  ]
}

Solutions:

1. Verify Request Body

   // Correct format for sending SMS
   {
     "phoneNumber": "+1234567890",
     "message": "Your message here"
   }
   
   // Correct format for sending OTP
   {
     "phoneNumber": "+1234567890",
     "language": "en",
     "channel": "sms"
   }

2. Check Phone Number Format

   • Must include country code with + prefix
   • Examples: +1234567890, +33123456789
   • No spaces or special characters except +

3. Verify Message Content

   • Message must be at least 1 character
   • OTP must be exactly 6 digits

4. Check Channel Value

   • For OTP: channel must be "sms" or "whatsapp" (lowercase)
   • Defaults to "sms" if omitted

📊 Rate Limiting

429 Too Many Requests

Symptoms:

• 429 status code
• "Rate limit exceeded" error message

Rate Limits:

• OTP sending: 3 requests per minute, 10 per hour, 20 per day (per phone number per API key)

Solutions:

1. Implement Exponential Backoff

   async function sendOTPWithRetry(
     phoneNumber,
     language,
     channel,
     maxRetries = 3
   ) {
     for (let i = 0; i < maxRetries; i++) {
       try {
         return await client.sendOTP(phoneNumber, language, channel);
       } catch (error) {
         if (error.status === 429 && i < maxRetries - 1) {
           // Wait with exponential backoff
           const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s
           await new Promise((resolve) => setTimeout(resolve, waitTime));
           continue;
         }
         throw error;
       }
     }
   }

2. Respect Rate Limits

   • Track your request frequency
   • Implement client-side rate limiting
   • Wait before retrying after 429 errors

3. Use Different Phone Numbers

   • Rate limits are per phone number
   • If testing, use different phone numbers to avoid hitting limits

📱 WhatsApp Channel Issues

502 Bad Gateway - WhatsApp Provider Error

Symptoms:

• 502 status code
• "WhatsApp OTP send failed" error message
• Error details from WhatsApp API

Solutions:

1. Check Phone Number Format

   • WhatsApp requires phone numbers in E.164 format with country code
   • Example: +1234567890 (not 1234567890)

2. Implement Fallback to SMS

   async function sendOTPWithFallback(phoneNumber, language) {
     try {
       // Try WhatsApp first
       return await client.sendOTP(phoneNumber, language, "whatsapp");
     } catch (error) {
       if (error.status === 502) {
         // Fallback to SMS if WhatsApp fails
         console.log("WhatsApp failed, falling back to SMS");
         return await client.sendOTP(phoneNumber, language, "sms");
       }
       throw error;
     }
   }

3. Handle Provider Errors Gracefully

   • WhatsApp provider errors are temporary
   • Implement retry logic with SMS fallback
   • Log errors for monitoring

4. Verify WhatsApp Service Availability

   • Contact Chinqit support if WhatsApp channel is consistently failing
   • Check if WhatsApp service is temporarily unavailable

🔄 Common Integration Issues

Messages Not Being Sent

Symptoms:

• Request succeeds but message not received
• No error but no delivery confirmation

Solutions:

1. Verify Phone Number

   • Ensure phone number is correct and active
   • Check country code is correct
   • Verify recipient can receive SMS

2. Check Message Content

   • Ensure message is not empty
   • Verify special characters are properly encoded
   • Check message length (standard SMS limits apply)

3. Handle Asynchronous Processing

   • Messages are queued and processed asynchronously
   • API returns immediately after queuing
   • Delivery may take a few seconds to minutes

OTP Verification Failing

Symptoms:

• OTP sent successfully but verification fails
• "Invalid OTP" or "OTP not found" errors

Solutions:

1. Check OTP Expiration

   • OTPs expire after 10 minutes
   • Ensure user enters OTP promptly
   • Request new OTP if expired

2. Verify OTP Format

   • OTP must be exactly 6 digits
   • No spaces or special characters
   • Example: "123456" (not "123 456" or "123-456")

3. Check Retry Limit

   • Maximum 3 verification attempts per OTP
   • After 3 failed attempts, OTP is invalidated
   • Request new OTP if retry limit exceeded

4. Match Channel

   • If OTP was sent via WhatsApp, verify with channel: "whatsapp"
   • If OTP was sent via SMS, verify with channel: "sms" (or omit, defaults to SMS)

5. Handle Case Sensitivity

   • Phone number must match exactly (including + prefix)
   • Ensure phone number format is consistent between send and verify

🌐 Network Issues

Connection Timeout

Symptoms:

• Request times out
• Network errors

Solutions:

1. Check Internet Connection

   • Verify your application has internet access
   • Test connectivity to https://sms.chinqit.com

2. Implement Timeout Handling

   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), 10000); // 10 second timeout
   
   try {
     const response = await fetch("https://sms.chinqit.com/messages/send", {
       signal: controller.signal,
       // ... other options
     });
     clearTimeout(timeoutId);
   } catch (error) {
     if (error.name === "AbortError") {
       console.error("Request timeout");
     }
   }

3. Retry Logic

   • Implement retry logic for transient network errors
   • Use exponential backoff
   • Don't retry on 4xx errors (client errors)

SSL/TLS Errors

Symptoms:

• SSL certificate errors
• TLS handshake failures

Solutions:

1. Verify HTTPS

   • Always use https://sms.chinqit.com (not http://)
   • Ensure your environment supports TLS 1.2+

2. Check Certificate

   • Ensure system clock is correct
   • Update CA certificates if needed
   • Contact Chinqit if certificate issues persist

🐛 Debugging Tips

Enable Request Logging

JavaScript:

async function sendMessage(phoneNumber, message) {
  console.log("Sending message:", { phoneNumber, message });

  try {
    const response = await fetch("https://sms.chinqit.com/messages/send", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.API_KEY,
      },
      body: JSON.stringify({ phoneNumber, message }),
    });

    console.log("Response status:", response.status);
    const data = await response.json();
    console.log("Response data:", data);

    return data;
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

Python:

import requests
import logging

logging.basicConfig(level=logging.DEBUG)

def send_message(phone_number, message):
    url = 'https://sms.chinqit.com/messages/send'
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': os.getenv('API_KEY')
    }
    data = {
        'phoneNumber': phone_number,
        'message': message
    }

    logging.debug(f'Sending request: {data}')
    response = requests.post(url, json=data, headers=headers)
    logging.debug(f'Response status: {response.status_code}')
    logging.debug(f'Response data: {response.json()}')

    return response.json()

Test API Connectivity

# Test basic connectivity
curl -X POST https://sms.chinqit.com/messages/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+1234567890", "message": "Test"}'

🆘 Still Having Issues?

1. Check Documentation:

   • API Reference - Complete endpoint documentation
   • API Usage Guide - Code samples and examples

2. Review Error Responses:

   • Check the message field for specific error details
   • Review errors array for validation issues
   • Note the HTTP status code

3. Common Solutions:

   • Verify API key is correct and active
   • Check request format matches API specification
   • Ensure phone numbers are in E.164 format
   • Implement proper error handling and retry logic
   • Contact Chinqit support for persistent issues

---

Need more help? Contact Chinqit support with:

• Your API key (masked)
• Error message and status code
• Request details (without sensitive data)
• Steps to reproduce the issue