Error Codes - Trackly SMS

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

Status	Meaning
`200`	Success
`201`	Created - The resource was created, or the message was queued
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid credentials
`402`	Payment Required - Billing issue (phone validation)
`403`	Forbidden - Account suspended, or product not enabled
`404`	Not Found - The requested resource does not exist
`410`	Gone - Endpoint retired
`413`	Payload Too Large - Request exceeds a size or count limit
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong
`503`	Service Unavailable - Upstream provider temporarily down

Authentication Errors (401)

Code	Message	Solution
`invalid_credentials`	Missing or invalid API key	Include `X-Api-Key` header with a valid key

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

Validation Errors

Send Endpoints (v2)

Code	HTTP	Message	Solution
`missing_to`	400	to is required	Provide the `to` field
`missing_list_number`	400	list_number is required	Provide the `list_number` field
`missing_body`	400	body is required	Provide the `body` field
`invalid_phone`	400	Invalid recipient phone number format	Use E.164 format (+1…)
`invalid_list_number`	400	Invalid list_number E.164 format	Use E.164 format for `list_number`
`too_many_messages`	413	Maximum 1000 messages per request	Split into smaller batches
`missing_messages`	400	messages array is required	Provide the `messages` array

Example: Missing Field

{
  "success": false,
  "code": "missing_to",
  "error": "to is required"
}

Example: Invalid Phone

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

Resource Errors (list_not_found)

list_not_found means the list_number you passed doesn’t match an active sending list on your account. It’s returned as 400 on the send and contacts endpoints, and as 404 on the links endpoints.

Code	HTTP	Message	Endpoints
`list_not_found`	400	Sending list not found for this list_number	Send, Contacts
`list_not_found`	404	Sending list not found	Links

{
  "error": "Sending list not found for this list_number",
  "code": "list_not_found"
}

Handling Errors

Python Example

import requests

response = requests.post(
    "https://api.tracklysms.com/api/v2/send",
    headers={"X-Api-Key": "your_key", "Content-Type": "application/json"},
    json={"to": "+14155551234", "body": "Hello", "list_number": "+18005551234"}
)

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 == 403:
    print("Account suspended or product not enabled")
else:
    print(f"Unexpected error: {response.status_code}")

JavaScript Example

try {
  const response = await axios.post(
    'https://api.tracklysms.com/api/v2/send',
    { to: '+14155551234', body: 'Hello', list_number: '+18005551234' },
    { 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 403:
        console.error('Account suspended or product not enabled');
        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 apply one platform-wide rate limit. Limits are enforced per endpoint, mostly per account — see API Limits & Best Practices for the full rate-limit, payload-size, and bulk-batch guidance.

Getting Help

If you encounter persistent errors:

Discord Support

Create a support ticket with /support new

FAQ

Check common questions

​Error Response Format

​HTTP Status Codes

​Authentication Errors (401)

​Validation Errors

​Send Endpoints (v2)

​Example: Missing Field

​Example: Invalid Phone

​Resource Errors (list_not_found)

​Handling Errors

​Python Example

​JavaScript Example

​Deprecation Headers

​API Limits

​Getting Help