Troubleshooting
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
401 UnauthorizedOn every request, with Basic Auth
- Confirm the username and password work in the EZ Texting web app. The API uses the same credentials.
- Check the header is exactly
Authorization: Basic <base64>where<base64>encodesusername:passwordwith no trailing newline. Shell users:echo -n, notecho. - If you're using an HTTP library's "auth" option, make sure it's not also sending a stale
Authorizationheader 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
400 Bad RequestRead 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 says | Fix |
|---|---|
Additional Account Verification Needed | The account needs verification before it can send. This isn't a code problem and retrying won't help. Contact support. |
INSUFFICIENT_BALANCE | The 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 out | The 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 / sendAt | sendAt 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 / phoneNumber | The 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 recipients | Pass toNumbers, groupIds, or both. |
Message doesn't have any content | Pass message, a media file (mediaUrl or mediaFileId), or messageTemplateId. Empty strings don't count. |
must be a well-formed email address | The 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 field | Over 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 supported | Remove 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, 200 | Page size must be 10, 20, 50, 100, or 200. |
Media url is too large | The file at mediaUrl is over the size limit. Compress or resize it. |
messageType | SMS 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 missing | Invalid 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
403 ForbiddenCredentials 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
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]=5551234and 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: thefromNumberisn't a number on your account.
I get 415 Unsupported Media Type
415 Unsupported Media TypeAdd Content-Type: application/json to requests with a body.
I get 429 Too Many Requests
429 Too Many RequestsYou'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
500 Internal Server ErrorFor 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:
- Check status.eztexting.com.
- Confirm the same request fails from the API reference's Try It.
- 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 says | Meaning | Next step |
|---|---|---|
total_delivered > 0 | Delivered 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 > 0 | Still in flight. | Wait. Seconds is normal; minutes happens with large sends, carrier congestion, or review holds. Poll again with backoff. |
bounced > 0 | It was rejected downstream, for example by the carrier. | See step 3. |
total_not_sent > 0 | EZ Texting didn't attempt it. | See step 2. |
| Delivery report counts fewer recipients than your list | Some 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 withPOST /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 a400withINSUFFICIENT_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/messagesafter 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:
sendAthad 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:sendAtwas 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.
DELETEdoesn't unsend.
Webhook isn't firing
- Is the subscription there?
GET /v1/webhooks/subscriptions. If it's gone, repeated delivery failures may have removed it. Re-create it. - Right event?
inbound_text.receivedfor texts;keyword.opt_inonly fires for keyword opt-ins, not all inbound messages. - Is the URL reachable from the internet?
https://, valid certificate (orinsecureSsl: truein dev), no auth challenge, no IP allowlist. Test it by sending aPOSTwith an empty JSON body to the URL from a machine or online HTTP client outside your network. - Does your handler return
2xxquickly? A500, a redirect, or a slow response counts as a failure. - Tunnel expired? Dev subscriptions pointing at an old ngrok URL fail silently. Delete and re-create.
- Catch up: sweep
GET /v1/conversations?filters[unread][eq]=truefor anything you missed. → Two-way conversations
Webhook signature doesn't match
In order of likelihood:
- 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, notexpress.json().) - Wrong secret. Each subscription has its own. Dev and prod subscriptions have different secrets; check which one is firing.
- Wrong encoding. The header is Base64 of the raw HMAC-SHA256 digest, not hex.
- Wrong algorithm. SHA-256, not SHA-1 or MD5.
- 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 iffirstNameis 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, includingcustom1…custom5, use their label with spaces removed, so renaming a field in Custom Fields changes its tag. The built-inemailfield isn't available as a merge tag. Unmatched tags become empty text with no error. See Merge tags. - You sent to
toNumbersfor 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.
mediaUrlmust 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. OmitmessageTypeor setMMS. - Use
mediaFileId. Upload once withPOST /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;groupIdsAddon 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
Authorizationheader value or a webhook secret, - the response: status, the relevant headers (
X-Rate-Limit-Retry-After-Millisecondson429), 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.
Updated about 17 hours ago