Error Codes

Every error response from the Textingline API follows a consistent structure:

{
  "code": 33001,
  "message": "Authentication failed",
  "status": 401,
  "moreInfo": "https://docs.smsfactory.com/docs/error-codes"
}

Some errors include a details object with machine-parseable information about the failure. For example, the Recipients Not Opted In error includes the list of phone numbers that failed the check:

{
  "code": 33028,
  "message": "One or more recipients are not opted in to any group",
  "status": 400,
  "moreInfo": "https://docs.smsfactory.com/docs/error-codes",
  "details": {
    "notOptedIn": ["+18005551234", "+18005559876"],
    "totalNotOptedIn": 2
  }
}

The details field is only present for errors that provide it — most errors return only the four standard fields.

Error code reference

Authentication & Authorization

33001 — Authentication Failed

The provided API credentials are invalid, missing, or the account is disabled. Common causes include a missing or malformed Authorization header, incorrect credentials, or a revoked API key. See Authentication for setup details.

33004 — Number Not Owned

The from number in the request is not assigned to the authenticated account. You can only send messages from numbers that have been provisioned and assigned to your account.

33020 — Account Not Configured

The account is not fully configured for messaging. This typically means the sender number has no associated whitelabel configuration. Contact support to complete account setup.

33021 — User Not Active

The user account is suspended, deactivated, or pending activation. Contact support to restore access.

33022 — API Not Enabled

API access has not been enabled for this account. Contact support to enable API access.

Request Validation

33003 — Invalid Phone Number

The to or from phone number is not in a valid format. Phone numbers must be in E.164 format — starting with + followed by the country code and subscriber number (e.g., +18005551234). The from field also accpts short codes (5-6 digits, e.g., 12345).

33005 — Missing Required Field

A required field in the request body is missing. For send message: to, from, and body (when no mediaUrl is provided). For broadcast: recipients, from, and body (when no mediaUrl).

33006 — Invalid Message Type

The messageType field must be either SMS or MMS. This error is returned when an unsupported value is provided.

33016 — Invalid Message Content

The message body contains characters that are not supported for SMS transmission. The error response may include an additionalInfo field listing each invalid character and its position in the body.

33024 — Request Validation Failed

The request body failed general validation. This includes issues such as duplicate phone numbers in the recipients array for broadcast requests.

Sender & Recipient

33008 — Sender Number Not Available

The from number is not provisioned or not currently available for sending. The number may not have been set up, has been released, or is temporarily unavailable.

33009 — Sender Number Not Active

The from number exists in the system but is not in an active state. Possible states include pending, suspended, or deactivated. Contact support to activate the number.

33010 — Recipient Blocked

The recipient (to) phone number has been blocked. This may occur because the recipient has opted out or the number appears on a block list. Note: in broadcast sends, blocked recipients are silently skipped rather than returning this error.

33011 — Sender Blocked

The sender (from) phone number has been blocked or suspended. Contact support to resolve this issue.

33025 — Unsupported Carrier

The recipient's carrier is not supported for messaging. This occurs when the carrier associated with the destination phone number cannot be used for message delivery. Try a different recipient number or contact support if you believe this is an error.

33028 — Recipients Not Opted In

One or more recipients are not opted in to any group owned by your account. Every recipient must be an active contact with at least one group membership before a message can be sent.

The error response includes a details object listing the phone numbers that failed the check:

{
  "code": 33028,
  "message": "One or more recipients are not opted in to any group",
  "status": 400,
  "moreInfo": "https://docs.smsfactory.com/docs/error-codes",
  "details": {
    "notOptedIn": ["+18005551234", "+18005559876"],
    "totalNotOptedIn": 2
  }
}

For single messages: The request fails if the recipient is not opted in. For broadcasts: The entire request fails if any recipient is not opted in. Remove the non-opted-in numbers from the recipients array and retry.

Content & Compliance

33019 — Non-Compliant Message Content

The message body violates messaging compliance rules. All outbound messages are screened against industry standards including SHAFT content (Sex, Hate, Alcohol, Firearms, Tobacco), phishing, fraud indicators, and regulated industries. See Compliance for full details.

Media

33014 — Media Too Large

The media file exceeds the maximum allowed size of 600 KB (614,400 bytes). Reduce the file size or use a lower-resolution version before retrying.

33015 — Media Type Not Supported

The media file has a MIME type that is not supported. See MMS & Media for the full list of accepted types.

33017 — Media Upload Failed

The media file could not be downloaded or processed. Common causes include an unreachable URL, server timeout, or a corrupted file. Verify the URL is publicly accessible and returns a valid media file.

33018 — Media URL Not Allowed

The mediaUrl failed security validation. The URL must use http:// or https://, point to a publicly accessible resource, and must not resolve to a private or internal IP address.

33026 — Media Download Failed

The media file could not be downloaded from the provided URL. Common causes include the URL returning a 404 (file not found), the remote server being unreachable, or a connection timeout. Verify the URL is publicly accessible and returns a valid media file before retrying.

Rate Limits & Quotas

33002 — Rate Limit Exceeded

The account has exceeded the allowed number of requests within the current rate-limit window. Check the X-RateLimit-* response headers and wait until the Retry-After period has elapsed. See Rate Limits for default limits per endpoint.

33012 — Daily Quota Reached

The account has reached its daily messaging quota. The quota resets at midnight UTC. Contact support if you need a higher daily limit.

33023 — Insufficient Credits

The account does not have enough credits to send the requested message. See MMS & Media for credit costs per message type.

Delivery & Processing

Note: Provider delivery failures (e.g., recipient opted out, invalid destination) do not return an HTTP error. Instead, the API returns a 201 response with status: failed along with errorType and errorMessage fields describing the reason. See Send a Message for the full list of error types.

33013 — Duplicate Idempotency Key

A message with the same idempotencyKey is currently being processed or a conflict was detected. When an idempotent request completes successfully and is retried, the original response is returned — this error only occurs when a conflict prevents the lookup. See Idempotency for best practices.

33000 — Unexpected Error

An unhandled internal error occurred. This is a catch-all for errors that do not match a more specific code. If you receive this error repeatedly, contact support with the request details and timestamps.

Message error types

When a message is accepted but fails at the provider or carrier level, the API returns a 201 response with status: failed (or a webhook event with status failed / undelivered). The errorType field classifies the failure reason and the errorMessage field provides a human-readable description.

These error types are distinct from HTTP error codes — they represent delivery-level failures, not request-level errors.

Handling errors

• 4xx errors indicate a problem with your request. Check the code and message fields, fix the issue, and retry.
• 429 errors mean you've hit a rate limit. Wait for the duration indicated by the Retry-After header before retrying.
• 5xx errors indicate a server-side issue. Retry with exponential backoff. Use idempotency keys to prevent duplicates on retries.