Authentication Troubleshooting

Common authentication errors and their solutions when using the Communications API.

Error Response Format

Authentication errors typically return with 200 OK status but contain error information in the response body:

[
  {
    "WarningMessages": [],
    "errorMsg": "Error description here",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Common Authentication Errors

Invalid Customer Credentials

[
  {
    "WarningMessages": [],
    "errorMsg": "Data is not valid, no messages sent",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Common Causes:

• Incorrect CustomerId or Password in the payload
• Expired or revoked API credentials
• Missing authentication fields in request body

Solutions:

1. Verify CustomerId and Password are correct and active
2. Ensure credentials are included in the messageData payload (not headers)
3. Contact support if credentials appear valid but authentication fails
4. Check for typos or extra whitespace in credential values

Insufficient Permissions

[
  {
    "WarningMessages": [
      "Customer does not allow sending SMS"
    ],
    "errorMsg": null,
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Solutions:

• Check customer account permissions for SMS/Email sending
• Contact customer administrator to enable messaging permissions
• Verify account is active and in good standing

Partner Not Enabled

[
  {
    "WarningMessages": [
      "Partner account not authorized for this customer"
    ],
    "errorMsg": null,
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

For Partner Authentication:

• Verify customer has authorized your partner application
• Check that partner callback has been received and processed
• Ensure you're using the correct customer-specific API key
• Confirm partner account is active and approved

Missing Authentication Fields

[
  {
    "WarningMessages": [],
    "errorMsg": "Required authentication fields missing",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Solutions:

1. Ensure both CustomerId and Password are present in payload
2. Check payload structure matches expected format:

   {
     "messageData": [{
       "CustomerId": "your-customer-id",
       "Password": "your-api-key",
       "message": "...",
       "recipients": [...]
     }]
   }

Authentication Method Issues

Using Wrong Authentication Method

Problem: Trying to use header-based authentication

// ❌ Wrong - Don't use Authorization headers
headers: {
  'Authorization': 'Bearer your-token',
  'X-Customer-ID': 'customer-123'
}

Solution: Use payload-based authentication

// ✅ Correct - Include credentials in payload
const payload = {
  messageData: [{
    CustomerId: "customer-123",
    Password: "your-api-key",
    message: "Hello world",
    recipients: ["+447700900123"]
  }]
};

Payload Structure Errors

Problem: Wrong payload structure

// ❌ Wrong structure
{
  "customerId": "123",
  "apiKey": "abc",
  "messages": [...]
}

Solution: Correct payload structure

// ✅ Correct structure
{
  "messageData": [{
    "CustomerId": "123",
    "Password": "abc",
    "message": "content",
    "recipients": [...]
  }]
}

Debugging Authentication Issues

1. Verify Credential Format

function validateCredentials(customerId, password) {
    if (!customerId || !password) {
        throw new Error('Missing CustomerId or Password');
    }
    
    if (typeof customerId !== 'string' || typeof password !== 'string') {
        throw new Error('Credentials must be strings');
    }
    
    if (customerId.trim() !== customerId || password.trim() !== password) {
        console.warn('Credentials contain leading/trailing whitespace');
    }
    
    return true;
}

2. Test Authentication Separately

async function testAuthentication(customerId, password) {
    const testPayload = {
        messageData: [{
            CustomerId: customerId,
            Password: password,
            recipients: ["+447700900000"], // Invalid test number
            message: "Authentication test"
        }]
    };
    
    try {
        const response = await fetch('https://m5api.groupcall.com/api/SendMessage_V3/SMS', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(testPayload)
        });
        
        const result = await response.json();
        
        // Check if error is auth-related vs. recipient-related
        if (result[0].errorMsg === "Data is not valid, no messages sent") {
            return { status: 'auth_failed', message: 'Invalid credentials' };
        } else if (result[0].WarningMessages?.includes("No recipients with valid addresses")) {
            return { status: 'auth_success', message: 'Credentials valid' };
        } else {
            return { status: 'unknown', result };
        }
    } catch (error) {
        return { status: 'network_error', error: error.message };
    }
}

3. Environment-Specific Issues

Development vs Production:

• Ensure using correct environment credentials
• Sandbox credentials won't work in production
• Check API endpoint URLs are correct

Configuration Issues:

// Check environment variables are loaded
console.log('CustomerId configured:', !!process.env.CUSTOMER_ID);
console.log('Password configured:', !!process.env.API_PASSWORD);

// Verify values (without logging actual credentials)
console.log('CustomerId length:', process.env.CUSTOMER_ID?.length);
console.log('Password length:', process.env.API_PASSWORD?.length);

When to Contact Support

Contact support if:

• Credentials appear correct but authentication consistently fails
• You receive unexpected authentication errors
• Partner authorization callback is not being received
• Account permissions need to be modified

Include in Support Request:

• Customer ID (safe to share)
• Error messages received
• Timestamp of failed requests
• Whether this is a new integration or previously working setup

---

Related Documentation:

• Authentication Overview
• Customer Authentication
• Partner Authentication
• API Errors