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"
}

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 valid E.164 format. Phone numbers must start with + followed by the country code and subscriber number (e.g., +18005551234).

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.

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 1 MB (1,048,576 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.

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.

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.