Public API — Error Reference

All API errors follow a consistent JSON response format and use error codes in the 33000–33999 range. Each error includes a moreInfo URL pointing to this page for quick reference.

Error Response Format

Every error response returns a JSON object with the following structure:

{
  "code": 33001,
  "message": "Authentication failed",
  "status": 401,
  "moreInfo": "https://docs.smsfactory.com/page/errors/33001"
}

Error Code Reference

General Errors

33000 — Unexpected Error

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

33007 — Message Send Failed

The message (or broadcast job) could not be created or delivered due to an internal error in the messaging pipeline. Retry the request; if the problem persists, contact support.

Authentication & Authorization Errors

33001 — Authentication Failed

The provided API credentials are invalid, missing, or the account is disabled. Verify your Authorization header uses the correct format:

Authorization: Basic <base64(keyId:keySecret)>

Common causes:

• Missing or malformed Authorization header
• Incorrect keyId or keySecret
• API key has been revoked or expired
• Account is suspended or disabled

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.

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: This error applies to single-message sends only. Blocked recipients in broadcast sends are silently skipped.

33011 — Sender Blocked

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

Rate Limiting Errors

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 before retrying.

Default rate limits:

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.

Validation Errors

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. Required fields depend on the endpoint:

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 1-based position in the body.

Content Compliance Errors

33019 — Non-Compliant Message Content

The message body violates messaging compliance rules. All outbound messages are automatically screened against industry compliance standards, including but not limited to:

• SHAFT content — Sex, Hate, Alcohol, Firearms, Tobacco
• Phishing — Deceptive links or social engineering attempts
• Fraud indicators — Scam patterns, impersonation, or misleading content
• Regulated industries — Cannabis, gambling, lending (where applicable)

Review and modify the message body to comply with messaging guidelines before retrying.

Sender Number Errors

33008 — Sender Number Not Available

The from number is not provisioned or not currently available for sending. This may indicate the number has not 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.

Idempotency Errors

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 is only returned when a conflict prevents the idempotent lookup from completing.

Tip: Use unique, descriptive idempotency keys (e.g., order-12345-shipment-notification) to safely retry requests without creating duplicate messages.

Media Errors (MMS)

33014 — Media Too Large

The media file referenced by mediaUrl 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 at the mediaUrl has a MIME type that is not supported. The following MIME types are accepted:

33017 — Media Upload Failed

The media file at the provided mediaUrl could not be downloaded or processed. Common causes:

• The URL is unreachable or returned an HTTP error
• The server timed out while downloading the file
• The file is corrupted or unreadable

Verify the URL is publicly accessible and returns a valid media file.

33018 — Media URL Not Allowed

The provided mediaUrl failed security validation. The URL may point to a disallowed host, a private/internal network address, or use a protocol that is not permitted.

Requirements for mediaUrl:

• Must use http:// or https:// protocol
• Must point to a publicly accessible resource
• Must not resolve to a private or internal IP address

Rate Limit Response Headers

Every response from the API includes rate limit information in the following headers:

MMS Media Requirements

When sending MMS messages, the mediaUrl must point to a publicly accessible media file that meets the following requirements:

If mediaUrl is provided without a body, the message is sent as MMS with media only. You may include both body and mediaUrl for an MMS with text and media.