Error Message Catalog

Learn how to fix error responses from the API

All error messages returned by the Mobile Text Alerts API follow a consistent JSON structure. This page gives examples of error responses, the specific scenarios that can trigger each error, and how to resolve them.

Error Body Structure

All error responses use Content-Type: application/json and contain the following fields:

Error body structure: { httpCode, message, timestamp, type, name, requestId }

Field	Type	Description
httpCode	number	The HTTP status code of the request (e.g. 400, 429).
message	string	A human-readable description of the specific error.
timestamp	string (ISO 8601)	This is an ISO 8601-formatted string. This may include an offset timestamp, which indicates how far the local time is from UTC. Example: "2026-05-01T13:43:09-05:00"
type	string (enum)	Machine-readable error category.
name	string (enum)	Exception class name.
requestId	string (UUID)	A unique identifier for each request. Include this when contacting support.

Note: 403 errors may also include a reason field. It adds context about why access was denied, such as the account restriction type. This field may be null.

Rate limit response headers

All API responses include response headers to provide information about your account's rate limit usage.

Error HTTP status code examples

400 — Bad Request

This indicates the request was malformed or is missing a required field. The message field will describe the specific problem.

Missing Required Field

The /send endpoint requires at least one content field: message, image, or templateId.

Example: POST /send The following response is returned when the message field is omitted.

{
    "httpCode":400,
    "message":"message, image, or templateId required",
    "timestamp":"2026-05-01T13:43:09-05:00",
    "type":"invalid_field_error",
    "name":"MTAInvalidFieldError",
    "requestId":"bb31b127-b4e5-44e5-a4af-daa57a52ad4a"
}

Fix: Include at least one content field — message, image, or templateId.

Character Limit Exceeded

The message you are trying to send is too long and exceeds the character limit. SMS messages are limited to 160 characters while MMS can be longer.

Example: POST /send The following response is returned when the message field contains too many characters.

{
    "httpCode":400,
    "message":"Messages cannot be longer than 2000 characters.",
    "timestamp":"2026-05-01T13:35:10-05:00",
    "type":"invalid_field_error",
    "name":"MTAInvalidFieldError",
    "requestId":"b76efd2c-81b8-4ebf-ad14-06ac1e38640a"
    }     

Fix: Shorten your message content.

Template requires linkId

When using a templateId that corresponds to a template containing a link, you must also provide a linkId.

Example: POST /send The following response is returned when the request includes a templateId for a template that contains a link.

{
  "httpCode":  400,
  "message": "linkId is required when using a template that contains a link.",
  "timestamp": "2026-05-01T13:43:09-05:00",
  "type":"invalid_field_error",
  "name":"MTAInvalidFieldError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Fix: Add the linkId for the link defined in your controlled template. You can retrieve available links via the Links endpoints.

Invalid recipient

Phone numbers in the subscribers field that cannot be parsed as valid numbers will be flagged as invalid.

Example: POST /send The following response is returned when the subscribers field contains an invalid number.

{
    "httpCode":400,
    "message":"Given number 1122333 is not valid.",
    "timestamp":"2026-05-01T14:04:28-05:00",
    "type":"invalid_field_error",
    "name":"MTAInvalidFieldError",
    "requestId":"8ab24cc7-9949-440e-bfed-d8be3b0173f4"
}

Fix: Use /send/validate-recipients to return invalid numbers in the invalidRecipients array instead of triggering a top-level 400. This lets you filter them before sending.

Duplicate Subscriber

If you add a subscriber that already exists on your account, that subscriber is updated and no error message is shown.

Example: A subscriber is added in a POST request to the /subscribers endpoint, but a subscriber with this number already exists.

Request:

curl --location --request POST 'https://api.platform.com/v3/subscribers' \
  --header 'Authorization: Bearer <APIKey>' \
  --header 'Content-Type: application/json' \
  --data '{"firstName": "FirstName","lastName": "LastName","number": "[phone]","email": "[email protected]"}'

Response: The API does not return an error. It returns an update for that subscriber.

{"message":"Subscriber updated successfully.",
    "data":{
        "id":111713494,
        "firstName":"FirstName",
        "lastName":"LastName",
        "email":"[email protected]",
        "number":8002223333,"e164Number":"[phone]",
        "date":"2026-04-13T15:32:32.000Z",
        "countryId":209,
        "groups":[],
        "subscriberFieldData":[],
        "signupMethod":5,
        "longNumber":8002223333,
        "carrierId":41
    }
}

401 — Unauthorized

A 401 response indicates a request did not include a valid API key, or the key has been revoked. The API uses Bearer token authentication — every request must include a valid Authorization header.

Missing Authorization Header

Example: POST /send The following response is returned when the Authorization header is missing:

{   "httpCode":401,
    "message":"Unauthorized [AUTH-GLOBAL-001]",
    "timestamp":"2026-05-14T14:43:45-05:00",
    "type":"unauthorized_error",
    "name":"MTAUnauthorizedError",
    "requestId":"2742fa1c-0580-4609-9b82-8c6af6a601b4"
}

Fix: Include your account API key in the Authorization header. For example: --header 'Authorization: Bearer 3099eebf-7661-5458-930e-65cd058a0b03'. See Get an API Key to learn more.

Invalid, malformed, or expired API key

Example: POST /send The following response is returned when the Authorization header contains an invalid API key:

{   "httpCode":401,
    "message":"Unauthorized [AUTH-GLOBAL-001]",
    "timestamp":"2026-05-14T14:43:45-05:00",
    "type":"unauthorized_error",
    "name":"MTAUnauthorizedError",
    "requestId":"2742fa1c-0580-4609-9b82-8c6af6a601b4"
}

Fix: Make sure the API key you are using matches the key shown in the dashboard. See Get an API Key to learn more.

403 — Forbidden

For this type of error, the API key is valid, but your account does not have permission to perform the requested action.

Possible reasons your account may be restricted from certain actions:

• Your account is suspended or restricted.

• You have a trial account and are attempting a non-template message send.

• You are trying to use a feature that is not enabled for your account, such as iMessage sending.

• The payment method on your account has expired or been declined.

The optional reason field provides additional context for some responses:

Reason value	Cause
EXPIRED_TRIAL_ACCOUNT	The trial period has ended for your account.
DISABLED_ACCOUNT	The account has been disabled. Contact support to learn more.
PAUSED_ACCOUNT	Your account's subscription has been paused.
CANCELED_ACCOUNT	Your account's subscription has been canceled.
DECLINED_CARD	The payment method on your account has been declined.
EXPIRED_CARD	The payment method on your account has expired.

Fix: If you are having account issues, contact support to ensure your account is enabled for the features you need.

409 — Conflict

This type of error is returned when a duplicate request is detected. The /send endpoint supports idempotency via an X-Request-Id header.

Example: POST /send The following response is returned for a repeat request. It confirms that the original request succeeded.

{
  "httpCode":  409,
  "message":   "Duplicate request detected. The request with this X-Request-Id has already been processed.",
  "timestamp": "2026-03-04T19:24:00.365Z",
  "type":      "conflict_error",
  "name":      "MTAConflictError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Fix: Include a unique X-Request-Id header on each /send call. If a network error leaves you unsure whether the request succeeded, you can safely re-send with the same X-Request-Id. The API will either confirm the original succeeded (409) or process as a new request.

429 — Rate Limit Exceeded

This type of error indicates too many requests were made within the allowed time window. Rate limits vary by endpoint. See Rate Limits to learn more about specific endpoint limits.

Example: POST /send The following response is returned when you exceed the rate limit of 25 requests every 15 seconds for message sends.

{
  "httpCode":  429,
  "message":   "Too many requests. You have exceeded the rate limit for this endpoint. Please wait before retrying.",
  "timestamp": "2026-04-04T19:24:00.365Z",
  "type":      "rate_limit_error",
  "name":      "MTARateLimitError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Fix: You can track your rate limit usage in the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers.

For large-scale subscriber changes, the Bulk Create/Update Subscribers endpoints are recommended.

500 — Internal Server Error

This error type is returned when an unexpected error occurs on the server. It is not caused by your request.

Example:

{
  "httpCode":  500,
  "message":   "An unexpected server error occurred. Please try again or contact support if this persists.",
  "timestamp": "2025-03-04T19:24:00.365Z",
  "type":      "internal_server_error",
  "name":      "MTAInternalServerError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Fix: If you receive a 500, retry after a short delay. If the error persists, contact support and include the following details:

• Request URL

• Request headers and body

• Request ID