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

All error responses are JSON objects. The error field is always present. Two additional fields may be present depending on the endpoint:

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

Field	Type	Always present?	Description
`error`	string	Yes	Human-readable description of the error.
`code`	string	Mostly	Machine-readable error code for programmatic handling. Present on virtually all v2 API errors, including the `403 Account is suspended` response; a few legacy paths may omit it, so defensively check for its presence.
`message`	string	Sometimes	Optional supplementary detail. Some endpoints (notably v1 phone validation and a few v2 paths) include a third `message` field with additional context; most do not.

Treat error as guaranteed and code/message as optional. Switch on code when present and fall back to the error text otherwise.

Authentication Errors (401)

Returned when the request is missing valid authentication credentials.

Error Code	Message	Description
`invalid_credentials`	Missing or invalid API key	The `X-Api-Key` header is missing or invalid. 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 credentials",
  "code": "invalid_credentials"
}

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.
`missing_from`	from is required	The sending number/list (`from`, `from_phone_number_id`) was not provided.
`missing_to_number`	to_number is required	The `to_number` field was not provided on a raw send.
`missing_phones`	phones array is required and must be non-empty	The `phones` array (batch phone validation) was not provided or is empty.
`invalid_force`	force must be a boolean	The `force` field was not a strict boolean (string `"true"` / int `1` are rejected).
`invalid_channel`	channel must be one of: sms, voice, auto	The OTP `channel` value is not one of the allowed options.
`missing_consent_method`	consent_method is required	TCPA consent method was not provided when adding/resubscribing a contact.
`invalid_consent_method`	Invalid consent_method	Provided consent method is not one of the allowed values.
`verbal_not_valid_for_marketing`	Verbal consent not valid for marketing	Verbal consent cannot be used to opt a contact into marketing messages.
`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.
`missing_phone`	phone number is required	The `phone` field was not provided (single-number validation endpoint).
`phone_type_blocked`	Phone type blocked by account settings	The recipient line type (e.g. VOIP, landline) is blocked by the account’s OTP settings. Returned by OTP endpoints only.

Generic Input Validation

Error Code	Message	Description
`invalid_input`	Invalid input	The request payload could not be parsed or contains invalid structure.
`missing_fields`	Required fields missing	One or more required fields are absent from the request.
`missing_id`	id is required	A resource identifier was not provided.
`missing_url`	url is required	A `url` field was not provided.
`missing_url_or_offer`	url or offer_id is required	Either a raw URL or an offer reference must be provided.
`invalid_url`	Invalid URL	The URL is malformed or cannot be parsed.
`invalid_url_scheme`	URL scheme must be http or https	The URL uses an unsupported scheme.
`unsafe_url`	Unsafe URL	The URL points to a domain blocked by the carrier-safety list.
`url_too_long`	URL exceeds maximum length	The URL is longer than the per-endpoint maximum.
`field_too_long`	Field exceeds maximum length	A string field exceeds its per-endpoint character cap.
`too_long`	Value too long	Generic length-cap violation.
`invalid_metadata`	Invalid metadata	The `metadata` field is not a valid object.
`metadata_too_large`	Metadata exceeds maximum size	The `metadata` payload exceeds the per-endpoint byte cap.
`invalid_ip_address`	Invalid IP address	The `ip_address` field is not a valid IPv4 or IPv6 address.
`invalid_timestamp`	Invalid timestamp	The timestamp value cannot be parsed.
`mutually_exclusive`	Mutually exclusive fields provided	Two fields that may not coexist were both provided.
`payload_too_large`	Payload exceeds size limit	The total request body exceeds the 5 MB limit.
`required`	Field is required	Generic required-field violation. The accompanying `error` text identifies which field.
`validation_failed`	Validation failed	Generic validation rejection covering compound rules.

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.
`empty_filter_group`	Filter group cannot be empty	A filter group was provided with zero conditions.
`invalid_condition_type`	Invalid condition type	The audience condition `type` is not a recognized value.
`invalid_audience_id`	Invalid audience ID	An audience ID could not be parsed or is not a valid ObjectId.
`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.
`invalid_time_unit`	Invalid time unit	The time-based filter uses an unsupported unit (allowed: hours, days, weeks).
`missing_time_value`	Time value is required	A time-based filter is missing its numeric value.
`invalid_count_field`	Invalid count field	The count-based filter references a non-countable field.
`invalid_count_operator`	Invalid count operator	The count-based filter uses an unsupported operator.
`missing_count_value`	Count value is required	The count-based filter is missing its numeric threshold.
`invalid_revenue_field`	Invalid revenue field	The revenue filter references a non-existent field.
`invalid_revenue_operator`	Invalid revenue operator	The revenue filter uses an unsupported operator.
`missing_revenue_value`	Revenue value is required	The revenue filter is missing its numeric threshold.
`missing_revenue`	revenue is required	The `revenue` field was not provided on a record-revenue call.
`invalid_revenue`	Invalid revenue	The `revenue` value is not a non-negative number.
`invalid_carrier_operator`	Invalid carrier operator	The carrier filter uses an unsupported operator.
`missing_carrier_value`	Carrier value is required	The carrier filter is missing its target value.
`invalid_phone_numbers_operator`	Invalid phone_numbers operator	The phone-numbers filter uses an unsupported operator.
`missing_phone_numbers_value`	phone_numbers value is required	The phone-numbers filter is missing its array of values.
`invalid_timezone_operator`	Invalid timezone operator	The timezone filter uses an unsupported operator.
`missing_timezone_value`	Timezone value is required	The timezone filter is missing its target value.
`invalid_custom_field_operator`	Invalid custom field operator	A custom-field filter uses an unsupported operator.
`missing_custom_field_name`	custom field name is required	A custom-field filter is missing its `name`.
`missing_custom_field_value`	custom field value is required	A custom-field filter is missing its `value`.
`missing_custom_fields`	custom_fields are required	The `custom_fields` object is required for this operation.
`invalid_custom_fields`	Invalid custom_fields	The `custom_fields` payload could not be parsed.
`invalid_group_operator`	Invalid group operator	A filter group uses an unsupported logical operator (allowed: AND, OR).
`invalid_entities`	Invalid entities	The `entities` array contains values that aren’t recognized.
`missing_entities`	entities is required	The `entities` array was not provided to history/clear.
`invalid_events`	Invalid events	The `events` array contains unrecognized event names.

Schedule Validation

Error Code	Message	Description
`missing_send_type`	send_type is required	The `send_type` field was not provided.
`invalid_send_type`	Invalid send_type	The `send_type` value is not one of the allowed options.
`missing_send_date`	send_date is required	One-time schedule is missing its `send_date`.
`missing_send_time`	send_time is required	The `send_time` (HH:MM) was not provided.
`missing_start_date`	start_date is required	A repeating schedule is missing its `start_date`.
`missing_end_date`	end_date is required	A repeating schedule is missing its `end_date`.
`missing_is_repeating`	is_repeating is required	The `is_repeating` boolean was not provided.
`no_days_selected`	At least one day of week must be selected	A repeating weekly schedule has no `days_of_week` enabled.
`missing_blasts`	blasts is required	A blast schedule is missing its `blasts` array.
`missing_blast_message`	Each blast must have a message	A blast variant is missing its `message`.
`invalid_blast_percent`	Invalid blast percent	A blast variant’s `percent` is invalid or the totals don’t sum to 100.
`schedule_complete`	Schedule is already complete	Operation cannot be performed on a schedule that has finished.
`source_list_not_found`	Source list not found	A `source_lists` ID does not match any list on the account.

Offer / Partnership Offer Validation

Error Code	Message	Description
`missing_offer_id`	offer_id is required	The `offer_id` field was not provided.
`invalid_offer_id`	Invalid offer_id	The offer ID could not be parsed.
`invalid_offer_link_offer_id`	Invalid offer_link offer_id	An entry in `offer_links` references an invalid offer ID.
`invalid_offer_links`	Invalid offer_links	The `offer_links` array is malformed.
`invalid_payout_type`	payout_type must be one of: cpa, cpc	The `payout_type` value is not a recognized option.
`missing_attribution_type`	attribution_type is required	The revenue `attribution_type` was not provided.
`invalid_attribution_type`	Invalid attribution_type	The revenue `attribution_type` is not a recognized option.
`invalid_external_platform`	Invalid external_platform	The `external_platform` value is not one of the allowed options.

List / Contact / Resource Errors

Error Code	Message	Description
`contact_not_found`	Contact not found	The contact does not exist for this account.
`list_contact_not_found`	List contact not found	The contact is not subscribed to the specified list.
`message_not_found`	Message not found	The message ID does not match any message on the account.
`missing_message_id`	message_id is required	The `message_id` field was not provided.
`missing_list_identifier`	list_id or list_number is required	Neither `list_id` nor `list_number` was provided.
`missing_tracking_url`	tracking_url is required	The offer’s `tracking_url` was not provided.
`missing_timestamp`	timestamp is required	The `timestamp` field was not provided.
`id_collision`	ID collision	The provided client-supplied ID conflicts with an existing record.
`already_active`	Already active	Cannot reactivate — record is already in active state.
`voice_not_enabled`	Voice channel not enabled	The OTP voice channel is not enabled for this account.
`otp_not_active`	OTP not active	The OTP session has expired or is not in an active state.
`invalid_code`	Invalid code	The OTP code provided does not match.

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_contacts_with_validation`	Maximum reduced when use_validation=true	(smaller)	When `use_validation=true` is set on bulk contact create, the per-request cap is lower because each contact triggers a billable lookup.
`too_many_records`	Maximum 1000 records per request	1,000	The `records` array in a bulk import exceeds the limit.
`too_many_phones`	Maximum 500 phones per request	500	The `phones` array in batch phone validation 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 (a 24-character hexadecimal ID for most resources)

Forbidden / Access Errors (403)

Returned when a valid API key is presented but the account is not permitted to perform the requested action. The 403 Account is suspended response intentionally omits the code field — see Authentication.

Error Code	Message	Description
`product_not_enabled`	`{PRODUCT}` product not enabled for this account	The endpoint belongs to a product not enabled for your account. The actual code follows the pattern `{product}_not_enabled` (e.g. `email_not_enabled`, `partnerships_not_enabled`). Contact support to enable.
`billing_blocked`	Billing blocked	Account has an outstanding billing problem (failed charge, suspended billing).
`account_suspended`	Account is suspended	The account has been suspended; resolve billing or contact support.
`fraud_blocked`	Account flagged for fraud review	Account is in fraud-review hold; sends are paused until cleared.
`geo_restricted`	Geographic restriction	The recipient country is not enabled for this account.
`phone_type_blocked`	Phone type blocked by account settings	OTP recipient’s line type (VOIP/landline) is blocked by account settings.

Conflict Errors (409)

Returned when the request conflicts with the current state of the resource.

Error Code	Message	Description
`id_collision`	ID collision	A client-supplied ID conflicts with an existing record.
`already_active`	Already active	The record is already in the requested state.
`no_domain_configured`	No link domain configured for this list	The sending list has no link-shortener domain configured; cannot create or shorten links until one is set in the dashboard.

Rate-Limit / Throttling Errors (429)

Returned when the request is throttled by a per-endpoint rate limit (for example the OTP and phone-validation endpoints) or a per-account limit (such as a daily send cap). Retry with exponential backoff after the window resets.

Error Code	Message	Description
`rate_limited`	Rate limit exceeded	A per-endpoint rate limit (e.g. OTP or phone validation) was exceeded. Back off and retry after the window resets.
`daily_cap_exceeded`	Daily send cap exceeded	The account has hit its 24-hour send cap.
`cooling_off`	Cooling-off period in effect	Recipient is in a cooling-off window after a recent send.
`limit_reached`	Limit reached	A per-account or per-endpoint quota has been exhausted.

Server / Infrastructure Errors (5xx)

Returned when a subsystem fails. These are generally transient — retry with exponential backoff.

Error Code	HTTP	Message	Description
`send_failed`	500	Send failed	The send pipeline encountered an unrecoverable error.
`save_error`	500	Save error	A datastore write failed.
`queue_failed`	500	Queue failed	The send-queue insertion failed.
`provider_sync_failed`	502	Provider sync failed	An upstream provider (CRM/affiliate platform) sync did not complete.
`provider_error`	503	Provider unavailable	An upstream provider is unavailable.
`redis_unavailable`	503	Service unavailable	The rate-limiter / dedup cache is unreachable.
`circuit_open`	503	Circuit breaker open	A subsystem circuit breaker is open after repeated failures; backing off.

Handling Errors in Code

curl -i -X POST https://api.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"}

import requests

response = requests.post(
    "https://api.tracklysms.com/api/v2/send",
    headers={"X-Api-Key": "trk_your_api_key_here"},
    json={"list_number": "+14155551234", "to": "+14155556789", "body": "Hello!"}
)

if not response.ok:
    data = response.json()
    code = data.get("code")
    error = data.get("error")

    if code == "invalid_credentials":
        # Re-authenticate or alert
        pass
    elif code == "invalid_phone":
        # Skip this recipient or fix the number format
        pass
    elif code == "too_many_messages":
        # Split into smaller batches
        pass
    else:
        print(f"API error [{code}]: {error}")

const response = await fetch("https://api.tracklysms.com/api/v2/send", {
  method: "POST",
  headers: {
    "X-Api-Key": "trk_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    list_number: "+14155551234",
    to: "+14155556789",
    body: "Hello!",
  }),
});

if (!response.ok) {
  const data = await response.json();

  switch (data.code) {
    case "invalid_credentials":
      // Re-authenticate or alert
      break;
    case "invalid_phone":
      // Skip this recipient or fix the number format
      break;
    case "too_many_messages":
      // Split into smaller batches
      break;
    default:
      console.error(`API error [${data.code}]: ${data.error}`);
  }
}

​Error Codes

​Error Response Format

​Authentication Errors (401)

​Example

​Validation Errors (400)

​General Validation

​Send / Message Validation

​Phone Number Validation

​Generic Input Validation

​Creative Validation

​Contact Validation

​Audience Validation

​Schedule Validation

​Offer / Partnership Offer Validation

​List / Contact / Resource Errors

​Resource Limit Errors (413)

​Example

​Not Found Errors (404)

​Example

​Forbidden / Access Errors (403)

​Conflict Errors (409)

​Rate-Limit / Throttling Errors (429)

​Server / Infrastructure Errors (5xx)

​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

Generic Input Validation

Creative Validation

Contact Validation

Audience Validation

Schedule Validation

Offer / Partnership Offer Validation

List / Contact / Resource Errors

Resource Limit Errors (413)

Example

Not Found Errors (404)

Example

Forbidden / Access Errors (403)

Conflict Errors (409)

Rate-Limit / Throttling Errors (429)

Server / Infrastructure Errors (5xx)

Handling Errors in Code

Next Steps