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 credential is missing or unusable, or the request’s source IP is outside the key’s allowlist. Verify the key, its lifecycle state, and your application’s public outbound IP.

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 not sent as X-Api-Key or Authorization: Bearer <key>
Your application’s public outbound IP is outside the key’s allowlist
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"
}

Pending-send Approval

The SMS approval workflow separates creation, human review, and execution. Reconcile uncertain outcomes using the existing pending ID.

HTTP Status	Error Code	Recovery
403	`confirmation_required`	Direct or send-enabling operations require approval. Hold single or bulk SMS for review; email, OTP, and raw SMS have no pending-send workflow.
503	`send_policy_unavailable`	Current key policy could not be verified. Retry after authority is restored; do not bypass the approval requirement.
409	`pending_send_not_open`	Only a pending or approved hold can be cancelled. Read the returned `status`; executing or unknown outcomes require reconciliation.
409	`pending_send_not_approved`	Execution requires an unexpired approved hold. Read `status`; wait for approval or inspect the existing execution rather than creating a duplicate.
409	`sandbox_mode_mismatch`	Execute with an authorized same-account key in the hold’s sandbox/live mode.
409	`pending_send_render_changed`	The rendered review or configuration changed. Create a new hold for review.
409	`render_snapshot_missing`	The immutable review is missing or malformed. Reject or cancel the open hold and submit a new review.
409 / 503	`unknown_execution`	Publication or its durable claim is uncertain. Poll the same pending ID and inspect execution evidence; never automatically resubmit.
429	`too_many_pending_sends`	`reason` identifies `open_holds` or `holds_24h`. Respect `retry_after` and `Retry-After`; cancellation does not refund the rolling creation limit.
503	`pending_send_unavailable`	Admission or pending-record authority could not be read reliably. Retry the read after recovery; preserve the original creation idempotency key.
503	`unknown_hold`	Hold persistence is uncertain. Read the ID when present. If a network timeout omitted it, replay the same `Idempotency-Key` and exact body, then use a bounded recent-hold lookup; never create a replacement to resolve uncertainty.

Agent Account Setup

Creation is anonymous. Status reads use the setup request’s bearer capability before or after login; it grants neither account access nor send authority.

HTTP Status	Error Code	Recovery
400	`onboarding_invalid_request`	Supply only the documented business name and email.
401	`onboarding_invalid_token`	The status capability is missing or malformed; use the token returned at setup creation.
404	`onboarding_not_found`	The identifier/token does not match a retained setup request. After retention, recover an existing account through support.
429	`onboarding_rate_limited`	Respect `Retry-After` and bound polling; do not create replacement setup requests.
503	`onboarding_unavailable`	Safe setup admission or status storage is unavailable. Retry with backoff.

Owner confirmation and renewal are separate authenticated dashboard actions. Identity, account eligibility, expiry, and second-factor refusals must be resolved in the original setup tab.

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.
`invalid_contact_data`	contact_data must be an object	`contact_data`, its `custom_fields`, or one of its string macro fields has the wrong JSON type.
`invalid_wrap_links`	wrap_links must be a JSON boolean	A request with non-empty `linkOverrides` supplied `wrap_links` as a value other than JSON `true` or `false`.
`missing_to_number`	to_number is required	Returned as a per-record entry in the `errors` array of a bulk history-import request when a record’s `to_number` field is missing.
`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.
`contact_suppressed`	Recipient is suppressed	The recipient is opted out or blocked and cannot receive the message.
`link_overrides_require_wrap_links`	linkOverrides requires wrap_links=true	`linkOverrides` was supplied without `wrap_links: true`, so the `{{linkN}}` placeholders would never be substituted.
`link_override_invalid`	`{linkN}`: …	A `linkOverrides` entry is malformed: key is not `link1`…`link99`, more than 10 entries, an unsupported field, not exactly one of `offerId` / `partnershipOfferId` / `customUrl`, or a URL exceeds 2,048 characters before or after macro expansion.
`link_override_unsafe_url`	`{linkN}`: URL must use HTTPS	A `customUrl` is not absolute HTTPS, names an IP literal or non-public host, or contains macros in its authority (userinfo, host, or port).

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	A single contact’s payload exceeds the 4,000-byte (4 KB) cap. The 5 MB limit on the overall request body is enforced separately and returns a `413` that does not carry this code.
`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.
`queue_failed`	Failed to queue for delivery	A per-item `code` inside the `errors` array of a bulk email-send response (the request itself still returns `202`).

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.
`invalid_offer_link`	`offer_link {key}: an offer or a custom URL is required`	An entry in the `offer_links` array must reference either an offer or a custom URL — exactly one is required.
`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.
`save_error`	Save error	Returned as a `400` when a single contact’s subscription could not be saved; also appears as a per-record `code` in the `errors` array of the bulk history-import responses (`/v2/history/sends`, `/v2/history/clicks`, `/v2/history/revenue`).

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.
`already_active`	Already active	Cannot reactivate — record is already in active state.
`cooling_off`	Cooling-off period in effect	A contact who opted out via the STOP keyword cannot be resubscribed until the sending list’s post-STOP cooling-off window (default 30 days) has elapsed. Applies to every opt-in surface: the Contacts API, opt-in forms and the opt-in webhook; `cooling_off_days = 0` disables the window.
`limit_reached`	Maximum 5 webhook endpoints per account	The account already has 5 registered OTP webhook endpoints, the per-account maximum.
`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
Inspect errors and retry corrected items only when they were definitively not submitted; reconcile publication errors before considering another send

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”).
`offer_not_found`	Offer not found: `{ids}`	A `linkOverrides` `offerId` does not exist, is not active, or belongs to another account.
`partnership_offer_not_found`	Partnership offer not found: `{ids}`	A `linkOverrides` `partnershipOfferId` does not exist, is not active and OMS-enabled, or belongs to another account.

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.

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.
`account_suspended`	Account is suspended	The account has been suspended; resolve billing or contact support.
`list_not_allowed_for_key`	This API key is not allowed to send from this list_number	The key’s `send_policy.list_numbers` (see Who Am I) restricts it to other sending lists. Use an allowed list or a key without the restriction.
`schedule_not_allowed_for_capped_key`	Capped API keys cannot create or edit schedules	Scheduled delivery cannot enforce this key’s daily cap. Use the capped send endpoints. An exact status-only `off` or `archive` update remains available, subject to the normal execution lock.
`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.

Payment Required Errors (402)

Returned when a billing problem blocks the specific action being attempted.

Error Code	Message	Description
`billing_blocked`	Billing issue: `{reason}`	The account has a billing problem that blocks this action; `{reason}` describes the specific issue.

Conflict Errors (409)

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

Error Code	Message	Description
`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.
`offer_management_active`	Offer management owns offer writes for this account	Offer creation for this account is handled in the dashboard under Offers. `GET`, `PUT`, and `DELETE` on offers are unaffected.
`offer_access_not_active`	Self-affiliate offer access is not active	A send referenced a `partnershipOfferId` whose existing self-affiliate access is paused or rejected. The send does not reactivate it.
`key_not_active`	The key changed state before it could be paused; retry	`POST /v2/auth/api-keys/self/pause` raced another state change on the same key (a revoke, a pause from the dashboard, a rotation); nothing was changed. Keys inside their rotation grace window can pause.
`schedule_write_conflict`	Schedule changed during this update	The update was refused because the schedule changed concurrently. The response includes `schedule_id` and `retryable: false`; reload the schedule before submitting a revised update.
`schedule_write_outcome_unknown`	Schedule write outcome could not be confirmed	The response includes `schedule_id` and `retryable: false`. Inspect that schedule before any retry; a failed response does not prove the write failed.

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 OTP daily cap, or the calling API key’s `daily_send_cap` (live sends per UTC day, see Who Am I), has been reached. A bulk send is rejected as a whole when the batch does not fit.

A send that fails before publication normally releases its reserved API-key allowance. If that refund cannot be confirmed, the allowance may remain used for the original UTC day even though the message was not published. Check Who Am I for current usage before retrying a capped send.

Server / Infrastructure Errors (5xx)

Returned when a subsystem fails. Backoff is appropriate for read requests and definitively refused sends. A send timeout or publication error may follow submission; reconcile its message ID when available instead of automatically sending again.

Error Code	HTTP	Message	Description
`send_failed`	500	Send failed	The send pipeline encountered an unrecoverable error.
`id_collision`	500	Failed to generate unique link ID	The server could not mint a unique short-link ID. Retry the request.
`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.
`send_cap_unavailable`	503	Daily quota check or reservation could not be confirmed	The send was refused. An uncertain reservation may still count toward today’s cap. Retry with backoff.
`circuit_open`	503	Circuit breaker open	A dependency is temporarily unavailable and requests are being shed. Retry after a short backoff.

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

​Pending-send Approval

​Agent Account Setup

​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)

​Payment Required Errors (402)

​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

Pending-send Approval

Agent Account Setup

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)

Payment Required Errors (402)

Conflict Errors (409)

Rate-Limit / Throttling Errors (429)

Server / Infrastructure Errors (5xx)

Handling Errors in Code

Next Steps