Error Codes

All API errors follow a consistent JSON response format. When a request fails, the response body contains a structured error object that you can use for programmatic error handling.

Error Response Format

Every error response includes the following fields:

{
  "error": "API key required",
  "code": "missing_api_key"
}

Field	Type	Description
`error`	string	Human-readable description of the error
`code`	string	Machine-readable error code for programmatic use

Authentication Errors (401)

Returned when the request is missing valid authentication credentials.

Error Code	Message	Description
`missing_api_key`	API key required	The `X-Api-Key` header was not included in the request.
`invalid_api_key`	Invalid API key	The provided API key does not match any active key. Verify the key format (`trk_[32-char-alphanumeric]`) and that it has not been revoked.

API keys are sensitive credentials. Never expose them in client-side code, public repositories, or logs.

Troubleshooting authentication errors

Common Causes:

API key was revoked or rotated in the dashboard
Key is being sent in the wrong header (must be X-Api-Key, not Authorization)
Extra whitespace or newline characters in the key value

Resolution:

Verify your key in Dashboard > Settings > API Keys
Ensure the header is exactly X-Api-Key: trk_... with no extra spaces
Generate a new key if the current one may be compromised

Example

{
  "error": "Invalid API key",
  "code": "invalid_api_key"
}

Validation Errors (400)

Returned when the request payload is malformed, missing required fields, or contains invalid values.

General Validation

Error Code	Message	Description
`not_found`	Resource not found	The referenced resource does not exist or is not accessible.
`confirm_required`	confirm must be true	A destructive operation requires explicit confirmation via `confirm: true`.

Send / Message Validation

Error Code	Message	Description
`missing_to`	to is required	The `to` field (recipient phone number) was not provided.
`missing_list_number`	list_number is required	The `list_number` field (sending phone number) was not provided.
`missing_body`	body is required	The message `body` field was not provided.
`invalid_phone`	Invalid recipient phone number format	The `to` value is not a valid E.164 phone number (e.g. `+14155551234`).
`invalid_phone`	Invalid E.164 phone number format	A phone number field does not conform to E.164 format.
`invalid_list_number`	Invalid list_number E.164 format	The `list_number` value is not a valid E.164 phone number.
`not_sendable`	VOIP numbers not allowed by account settings	The recipient number was identified as VOIP and the account has VOIP sending disabled.
`missing_messages`	messages array is required	The `messages` array was not provided in a bulk send request.
`list_not_found`	Sending list not found for this list_number	No sending list is associated with the provided `list_number`.
`webhook_not_configured`	Webhook verification required before sending	The BYOC list requires webhook verification before messages can be sent.

Phone Number Validation

Error Code	Message	Description
`missing_phone_number`	phone_number is required	The `phone_number` field was not provided.

Creative Validation

Error Code	Message	Description
`missing_name`	name is required	The creative `name` field was not provided.
`missing_message`	message is required	The creative `message` field was not provided.
`missing_offer_links`	offer_links is required	The `offer_links` array was not provided for a creative that uses link placeholders.
`name_too_long`	name must be 255 characters or less	The creative name exceeds the 255 character limit.
`message_too_long`	message must be 1600 characters or less	The creative message exceeds the 1600 character limit.
`invalid_status`	status must be one of: …	The provided `status` value is not a valid option.
`invalid_creative_type`	creative_type must be one of: …	The provided `creative_type` value is not a valid option.
`missing_link_placeholder`	message must contain at least one {{linkN}} placeholder	The creative message does not contain a required `{{linkN}}` placeholder.
`missing_offer_links_for_placeholders`	Missing offer_links for placeholders: …	One or more `{{linkN}}` placeholders in the message do not have corresponding entries in `offer_links`.
`missing_offer_link_key`	offer_link key is required	An entry in the `offer_links` array is missing its `key` field.
`missing_offer_link_offer_id`	offer_link offer_id is required	An entry in the `offer_links` array is missing its `offer_id` field.
`offer_not_found`	Offer not found: …	The referenced offer ID does not exist in your account.

Contact Validation

Error Code	Message	Description
`missing_contacts`	contacts array is required	The `contacts` array was not provided in a bulk contact request.
`missing_records`	records array is required	The `records` array was not provided in a bulk import request.

Audience Validation

Error Code	Message	Description
`missing_filter`	filter is required	The audience `filter` object was not provided.
`missing_audiences`	audiences is required	The `audiences` array was not provided.
`invalid_condition_type`	Invalid condition type	The audience condition `type` is not a recognized value.
`invalid_time_field`	Invalid time field	The time-based filter references a field that does not exist or is not filterable.
`invalid_time_operator`	Invalid time operator	The time-based filter uses an operator that is not supported.

Troubleshooting validation errors

Common Causes:

Phone numbers missing the + prefix or country code (must be E.164 format like +14155551234)
Sending to a list_number that belongs to a different account
Bulk request arrays exceeding the 1,000 item limit
Creative message body exceeding the 1,600 character limit

Resolution:

Validate phone numbers match E.164 format before sending
Use the List endpoint to verify your list_number values
Check the code field in the error response for the specific validation that failed

Resource Limit Errors (413)

Returned when a bulk request exceeds the maximum number of items allowed per request.

Error Code	Message	Limit	Description
`too_many_messages`	Maximum 1000 messages per request	1,000	The `messages` array in a bulk send exceeds the limit.
`too_many_contacts`	Maximum 1000 contacts per request	1,000	The `contacts` array in a bulk contact operation exceeds the limit.
`too_many_records`	Maximum 1000 records per request	1,000	The `records` array in a bulk import exceeds the limit.

Example

{
  "error": "Maximum 1000 messages per request",
  "code": "too_many_messages"
}

To process more than 1,000 items, split your data into batches and send multiple requests sequentially.

Troubleshooting resource limit errors

Common Causes:

Attempting to send more than 1,000 messages in a single bulk request
Importing more than 1,000 contacts or records in one API call

Resolution:

Split large datasets into batches of 1,000 or fewer items
Process batches sequentially with error handling between each batch
Use the response error_count and errors array to identify and retry failed items

Not Found Errors (404)

Returned when the requested resource does not exist or is not accessible under your account.

Error Code	Message	Description
`not_found`	Resource not found	Generic not-found error. The message may include the specific resource type (e.g. “Contact not found”, “Creative not found”, “Schedule not found”).

Example

{
  "error": "Contact not found",
  "code": "not_found"
}

Troubleshooting not found errors

Common Causes:

Using an ID from a different account (all resources are account-scoped)
Referencing a resource that was deleted
Typo in the resource ID

Resolution:

Verify the resource exists by calling the corresponding List endpoint
Ensure your API key belongs to the same account that owns the resource
Check that you are using the correct ID format (MongoDB ObjectId for most resources)

Handling Errors in Code

curl -i -X POST https://app.tracklysms.com/api/v2/send \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "list_number": "+14155551234",
    "to": "+14155556789",
    "body": "Hello!"
  }'

# Check the HTTP status code and parse the JSON error response:
# HTTP/1.1 400 Bad Request
# {"error": "Invalid recipient phone number format", "code": "invalid_phone"}

API Reference

V2 API Reference

Messages (v2)

Contacts (v2)

Lists (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Data Import (v2)

Links (v2)

Webhooks (v2)

API Reference (v1 - Deprecated)

Error Codes

Error Codes

Error Response Format

Authentication Errors (401)

Example

Validation Errors (400)

General Validation

Send / Message Validation

Phone Number Validation

Creative Validation

Contact Validation

Audience Validation

Resource Limit Errors (413)

Example

Not Found Errors (404)

Example

Handling Errors in Code

Next Steps

API Limits & Best Practices

Send Message

API Reference

V2 API Reference

Messages (v2)

Contacts (v2)

Lists (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Data Import (v2)

Links (v2)

Webhooks (v2)

API Reference (v1 - Deprecated)

​Error Codes

​Error Response Format

​Authentication Errors (401)

​Example

​Validation Errors (400)

​General Validation

​Send / Message Validation

​Phone Number Validation

​Creative Validation

​Contact Validation

​Audience Validation

​Resource Limit Errors (413)

​Example

​Not Found Errors (404)

​Example

​Handling Errors in Code

​Next Steps

API Limits & Best Practices

Send Message

Error Codes

Error Response Format

Authentication Errors (401)

Example

Validation Errors (400)

General Validation

Send / Message Validation

Phone Number Validation

Creative Validation

Contact Validation

Audience Validation

Resource Limit Errors (413)

Example

Not Found Errors (404)

Example

Handling Errors in Code

Next Steps