Skip to main content
The Trackly SMS API uses standard HTTP status codes and returns detailed error information in the response body.

​
Error Response Format

All errors follow this format: 
{
  "error": "Human-readable error message",
  "code": "machine_readable_code"
}

​
HTTP Status Codes

StatusMeaning
200Success
201Created (for POST requests)
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong

​
Authentication Errors (401)

CodeMessageSolution
missing_api_keyAPI key requiredInclude X-Api-Key header
invalid_api_keyInvalid API keyCheck your API key is correct and active
{
  "error": "API key required",
  "code": "missing_api_key"
}

​
Validation Errors (400)

​
Message Endpoints

CodeMessageSolution
missing_toRecipient phone number (to_msisdn) is requiredProvide the to_msisdn field
missing_bodyMessage body is requiredProvide the body field
missing_fromSending number ID (from_phone_number_id) is requiredProvide from_phone_number_id
invalid_phoneInvalid phone number formatUse E.164 format (+1…)
too_many_messagesMaximum 1000 messages per requestSplit into smaller batches
missing_messagesMessages array is requiredProvide the messages array

​
Example: Missing Field

{
  "error": "Recipient phone number (to_msisdn) is required",
  "code": "missing_to"
}

​
Example: Invalid Phone

{
  "error": "Invalid phone number format",
  "code": "invalid_phone"
}

​
Resource Errors (404)

CodeMessageSolution
list_not_foundSending number not foundVerify the from_phone_number_id exists and is active
{
  "error": "Sending number not found",
  "code": "list_not_found"
}

​
Handling Errors

​
Python Example

import requests

response = requests.post(
    "https://app.tracklysms.com/api/v1/messages",
    headers={"X-Api-Key": "your_key", "Content-Type": "application/json"},
    json={"to": "+14155551234", "body": "Hello", "from_phone_number_id": "pn_123"}
)

if response.status_code == 201:
    result = response.json()
    print(f"Message queued: {result['message_id']}")
elif response.status_code == 401:
    print("Authentication failed - check your API key")
elif response.status_code == 400:
    error = response.json()
    print(f"Validation error: {error['error']} (code: {error['code']})")
elif response.status_code == 404:
    print("Resource not found - check your from_phone_number_id")
else:
    print(f"Unexpected error: {response.status_code}")

​
JavaScript Example

try {
  const response = await axios.post(
    'https://app.tracklysms.com/api/v1/messages',
    { to: '+14155551234', body: 'Hello', from_phone_number_id: 'pn_123' },
    { headers: { 'X-Api-Key': 'your_key' } }
  );

  console.log('Message queued:', response.data.message_id);
} catch (error) {
  if (error.response) {
    const { status, data } = error.response;

    switch (status) {
      case 401:
        console.error('Authentication failed');
        break;
      case 400:
        console.error(`Validation error: ${data.error}`);
        break;
      case 404:
        console.error('Resource not found');
        break;
      default:
        console.error(`Error ${status}: ${data.error}`);
    }
  }
}

​
Deprecation Headers

All v1 API responses include deprecation headers: 
X-API-Deprecated: v1 is deprecated
Deprecation: true
These headers indicate the API version is deprecated. Watch for announcements about the v2 API.

​
API Limits

Trackly SMS does not impose API rate limits. For payload size limits and bulk batch guidance, see API Limits & Best Practices.

​
Getting Help

If you encounter persistent errors:

Discord Support

Create a support ticket with /support new

FAQ

Check common questions