Troubleshooting

Start with the symptom
Each section below is something you can see (a status code, a message that never arrived, a webhook that went quiet), followed by the checks that usually explain it.
401400429Not deliveredWebhook silentSignature mismatch

Find the symptom, run the checks in order. Each section ends with what to send support if you're still stuck.


I get 401 Unauthorized

On every request, with Basic Auth

  1. Confirm the username and password work in the EZ Texting web app. The API uses the same credentials.
  2. Check the header is exactly Authorization: Basic <base64> where <base64> encodes username:password with no trailing newline. Shell users: echo -n, not echo.
  3. If you're using an HTTP library's "auth" option, make sure it's not also sending a stale Authorization header from a default config.

Credentials work in the web app, but every API call returns 401

Your plan may not include API access. Contact support to check.

On one specific ID, while other calls work

The ID belongs to a different account. A message, report, or similar ID that isn't yours returns 401, not 404. Common when copying an example ID from these docs.

After ~90 minutes, with a bearer token

The access token expired (lifetime 5400 s). Refresh it with POST /v1/tokens/refresh and retry. Build this in; don't wait for the 401. → Authentication

From /v1/tokens/refresh

The refresh token is expired (60 days) or was revoked. Create a new pair with /v1/tokens/create.

It works in the API reference but not in my code

The reference's Try It uses Basic Auth with what you typed. Capture the exact request your code sends (a proxy, or your HTTP library's debug logging) and compare the Authorization header byte for byte.


I get 400 Bad Request

Read the body. errors[].message almost always names the field:

{
  "status": 400,
  "title": "Malformed Request",
  "detail": "…",
  "errors": [{ "code": "…", "title": "Validation Failure", "message": "toNumbers[0]: …" }]
}

Common causes, most frequent first:

errors[].message saysFix
Additional Account Verification NeededThe account needs verification before it can send. This isn't a code problem and retrying won't help. Contact support.
INSUFFICIENT_BALANCEThe account doesn't have enough credits for the send. Check GET /v1/credits, buy credits (or turn on auto-refill in the web app), then send again.
The phone numbers that you're sending to are opted outThe number opted out: the contact replied STOP, or it was blocked with POST /v1/blocks. Don't retry. Check optOut on the contact before you send.
The scheduled time is in the past / sendAtsendAt must be ISO 8601 with an offset, for example 2027-11-18T09:00:00-08:00, and in the future. A past time usually means a missing offset or a server clock that's off.
Can't sort by field: …That field isn't sortable on this endpoint. For messages, sort by created (sort=created,desc), not sentAt.
Phone number is not valid / Invalid phone number … / toNumbers / phoneNumberThe number couldn't be parsed. Normalize to 11 digits: 15551234567. Too few or too many digits are the usual culprit. Placeholder values from a CRM, like 10000000000 or (Not Available), fail the same way, so filter them out before sending. → Phone number formatting
Message doesn't have any recipientsPass toNumbers, groupIds, or both.
Message doesn't have any contentPass message, a media file (mediaUrl or mediaFileId), or messageTemplateId. Empty strings don't count.
must be a well-formed email addressThe contact's email isn't a valid address. Leave the field out rather than sending a placeholder.
size must be between 0 and 20 / firstName / lastName / Invalid value … for custom fieldOver 20 characters (this applies to every custom field, not just custom1 … custom5), or a Date field that isn't MM-dd-yyyy. Put long values (URLs especially) in the message text. email and note allow more.
The character X is not supportedRemove or replace that character. Curly quotes are fine (they're converted); some symbols and alphabets aren't supported.
Value for size must be one of 10, 20, 50, 100, 200Page size must be 10, 20, 50, 100, or 200.
Media url is too largeThe file at mediaUrl is over the size limit. Compress or resize it.
messageTypeSMS or MMS, uppercase.
filters[…]The filter value is invalid, for example a partial phone number without % wildcards, or an unknown source. An unknown field or operator isn't an error: it's silently ignored and you get the unfiltered list.
Required request body is missingInvalid JSON. A trailing comma, single quotes, or a shell-quoting problem in cURL.

With strictValidation on (the default), one bad number among several rejects the whole send with 400. That's the feature working. Set it to false to skip bad numbers instead.


I get 403 Forbidden

Credentials are valid but the account can't do this. Usually the login belongs to an Operator or Agent teammate (only the account holder and Admin teammates can use the API), a feature not enabled on your plan (for example, keyword purchase, credit purchase by API) or a resource belonging to a different account. Retrying won't help; check the account in the web app or contact support.


I get 404 Not Found

  • On a contact: the phone number in the path doesn't match a stored contact. Check how it's stored with GET /v1/contacts?filters[phoneNumber][like]=5551234 and use the 11-digit form in the path.
  • On a message, template, group, or media file: wrong ID, or it was deleted. IDs are strings; make sure nothing stripped leading characters or parsed it as a number.
  • On an endpoint: check the path. All endpoints are under /v1/; /v1/webhooks/subscriptions, not /v1/webhooks.
  • On a send, From number is required: the account has no default number to send from.
  • On a send, number: … not found: the fromNumber isn't a number on your account.

I get 415 Unsupported Media Type

Add Content-Type: application/json to requests with a body.


I get 429 Too Many Requests

You've sent more than 200 requests in a minute. Wait the number of milliseconds in X-Rate-Limit-Retry-After-Milliseconds, then retry.

If this happens regularly, look for tight polling loops, or the same message sent with one request per recipient. Group sends, batch contact calls, and webhooks cut the request count. → Rate limits


I get 500 Internal Server Error

For reads, upserts, and deletes, retry with backoff (2 s, 4 s, 8 s …, max 5 attempts). For POST /v1/messages, don't retry. A 5xx can be returned after the send was accepted, so check whether it went out before sending again (Idempotency & retries). If it persists:

  1. Check status.eztexting.com.
  2. Confirm the same request fails from the API reference's Try It.
  3. Contact support with the endpoint, a redacted request body, the full response, and the timestamp (UTC).

Message accepted but not delivered

You got 201 and an id, but the phone didn't buzz. Work down this list.

1. Read the report.

curl https://a.eztexting.com/v1/message-reports/128443910003 \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD"
import os, requests

auth = (os.environ["EZTEXTING_USERNAME"], os.environ["EZTEXTING_PASSWORD"])
report = requests.get("https://a.eztexting.com/v1/message-reports/128443910003", auth=auth, timeout=30).json()
print(report["delivery"])
const credentials = Buffer.from(
  `${process.env.EZTEXTING_USERNAME}:${process.env.EZTEXTING_PASSWORD}`
).toString("base64");
const report = await (await fetch("https://a.eztexting.com/v1/message-reports/128443910003", {
  headers: { Authorization: `Basic ${credentials}` },
})).json();
console.log(report.delivery);
<?php
$ch = curl_init("https://a.eztexting.com/v1/message-reports/128443910003");
curl_setopt($ch, CURLOPT_USERPWD, getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$report = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($report['delivery']);
require "net/http"
require "json"

uri = URI("https://a.eztexting.com/v1/message-reports/128443910003")
req = Net::HTTP::Get.new(uri)
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
report = JSON.parse(Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }.body)
puts report["delivery"]
String basicAuth = Base64.getEncoder().encodeToString(
    (System.getenv("EZTEXTING_USERNAME") + ":" + System.getenv("EZTEXTING_PASSWORD")).getBytes());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://a.eztexting.com/v1/message-reports/128443910003"))
    .header("Authorization", "Basic " + basicAuth)
    .GET().build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes(
    $"{Environment.GetEnvironmentVariable("EZTEXTING_USERNAME")}:{Environment.GetEnvironmentVariable("EZTEXTING_PASSWORD")}"));
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);
var report = await client.GetFromJsonAsync<JsonElement>("https://a.eztexting.com/v1/message-reports/128443910003");
Console.WriteLine(report.GetProperty("delivery"));
req, _ := http.NewRequest("GET", "https://a.eztexting.com/v1/message-reports/128443910003", nil)
req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer resp.Body.Close()
var report map[string]any
json.NewDecoder(resp.Body).Decode(&report)
fmt.Println(report["delivery"])
Report saysMeaningNext step
total_delivered > 0Delivered to the handset (in rare cases, only confirmed as accepted by the carrier).Check the phone: wrong number? blocked contact on the handset? iMessage filtering "unknown senders"?
queued > 0Still in flight.Wait. Seconds is normal; minutes happens with large sends, carrier congestion, or review holds. Poll again with backoff.
bounced > 0It was rejected downstream, for example by the carrier.See step 3.
total_not_sent > 0EZ Texting didn't attempt it.See step 2.
Delivery report counts fewer recipients than your listSome numbers were invalid and skipped (strictValidation: false).Fix the formatting, or leave strictValidation at its default (true) so bad numbers fail with a 400.

2. If not_sent:

  • Opted out. GET /v1/contacts/{phoneNumber} → optOut: true. This covers contacts who replied STOP and numbers opted out with POST /v1/blocks. The platform will not deliver to this contact until they opt back in (by texting your keyword or START). You can't override this.
  • Out of credits. GET /v1/credits → totalCredits: 0. This happens to scheduled messages that come due after credits run out; a new send while out of credits is rejected up front with a 400 with INSUFFICIENT_BALANCE. Buy credits; the unsent message won't retry on its own, so send again.

3. If bounced:

  • Landline or VoIP. Most landlines and some VoIP numbers can't receive texts. Your sign-up form can ask for a mobile number.
  • Disconnected / invalid. Carrier says the number doesn't exist.
  • Carrier filtering. The number is real but the carrier dropped the message. Signs: a specific carrier (often one of the big three) bouncing while others deliver; new or unregistered sending number; message content with a public link shortener, ALL CAPS, or content outside your registered use case. Fixes are on the content and registration side. See Compliance. If you believe a legitimate message is being filtered, contact support with the message ID and the destination carrier; don't try to evade the filter by varying content.

4. If delivered but the person says they didn't get it: ask them to check blocked contacts and spam/"unknown sender" folders on the handset, and confirm the number. "Delivered" normally means the carrier handed it to the device.


Message delivered twice

  • Your code retried a POST /v1/messages after a timeout or an ambiguous failure. The first attempt succeeded. → Idempotency & retries
  • Your job queue redelivered a job that had already sent. Same fix.
  • Your upstream system fired the same event twice. Same fix: key sends on your own event ID.

Scheduled message didn't send, or sent at the wrong time

  • Wrong time: sendAt had no UTC offset and was interpreted differently than you assumed. Always include the offset: 2026-11-20T09:00:00-08:00.
  • Rejected with a 400: sendAt was in the past: "The scheduled time is in the past. Please choose a future time." Often a time-zone slip, or a clock skew in a container.
  • Didn't send: check GET /v1/campaign-info. Is it still pending? Was it deleted (DELETE /v1/messages) by a cancel path in your code? Did the account run out of credits before the send time?
  • Can't cancel: it already went out. DELETE doesn't unsend.

Webhook isn't firing

  1. Is the subscription there? GET /v1/webhooks/subscriptions. If it's gone, repeated delivery failures may have removed it. Re-create it.
  2. Right event? inbound_text.received for texts; keyword.opt_in only fires for keyword opt-ins, not all inbound messages.
  3. Is the URL reachable from the internet? https://, valid certificate (or insecureSsl: true in dev), no auth challenge, no IP allowlist. Test it by sending a POST with an empty JSON body to the URL from a machine or online HTTP client outside your network.
  4. Does your handler return 2xx quickly? A 500, a redirect, or a slow response counts as a failure.
  5. Tunnel expired? Dev subscriptions pointing at an old ngrok URL fail silently. Delete and re-create.
  6. Catch up: sweep GET /v1/conversations?filters[unread][eq]=true for anything you missed. → Two-way conversations

Webhook signature doesn't match

In order of likelihood:

  1. You hashed a re-serialized body. Middleware parsed the JSON and you re-encoded it before hashing. Hash the raw bytes as received. (Express: use express.raw() on that route, not express.json().)
  2. Wrong secret. Each subscription has its own. Dev and prod subscriptions have different secrets; check which one is firing.
  3. Wrong encoding. The header is Base64 of the raw HMAC-SHA256 digest, not hex.
  4. Wrong algorithm. SHA-256, not SHA-1 or MD5.
  5. Trailing newline added by your tooling when testing with a file.

Verify your implementation against the test vector on Webhooks before suspecting the platform. When logging a mismatch, log the body length and a short hash of the raw bytes, not the body itself (it's customer data) and not the secret.


Template variables came through blank

  • The contact doesn't have the field set. ${FirstName} is empty if firstName is empty. Upsert the contact with the values before sending.
  • The variable name doesn't match. Built-ins are ${FirstName} and ${LastName} (exact capitalization). Custom fields, including custom1 … custom5, use their label with spaces removed, so renaming a field in Custom Fields changes its tag. The built-in email field isn't available as a merge tag. Unmatched tags become empty text with no error. See Merge tags.
  • You sent to toNumbers for numbers that aren't contacts yet. Variables resolve from the contact record. Create the contact first (POST /v1/contacts, idempotent).
  • The value was too long and was rejected on upsert (20-character limit on names and custom slots). Check the upsert response.

MMS media didn't show up

  • The URL isn't public. mediaUrl must be fetchable by EZ Texting without auth: no localhost, no signed URLs that have expired, no CDN hotlink protection.
  • Too big or unsupported. 5 MB max; standard image, video, and audio formats.
  • Sent as SMS. If you passed messageType: "SMS" with media, the media is dropped. Omit messageType or set MMS.
  • Use mediaFileId. Upload once with POST /v1/media-files, then send by ID. Faster and not dependent on your CDN at send time.

Replies are going to the wrong number or thread

Your account has multiple sending numbers and you didn't set fromNumber. Replies to a customer should come from the same number they texted. Use toNumber from the inbound webhook payload as fromNumber on the reply.


Contacts I imported aren't receiving campaigns

  • They're opted out: GET /v1/contacts?filters[optOut][eq]=true&filters[groupName][like]=<group>.
  • They're not actually in the group: GET /v1/contact-groups/{id} and compare counts; groupIdsAdd on the batch upsert applies to every contact in that batch, so make sure it was set.
  • Numbers were normalized differently on import (10 digits vs 11) and created duplicates. Search by filters[phoneNumber][like].

Still stuck?

Contact support with:

  • the endpoint and method,
  • the request body with phone numbers and personal data redacted, and never the Authorization header value or a webhook secret,
  • the response: status, the relevant headers (X-Rate-Limit-Retry-After-Milliseconds on 429), and body,
  • any message, contact, or webhook IDs involved,
  • when it started (UTC), and whether it's every request or intermittent.

That's usually enough to resolve it in one round trip.


Did this page help you?