When you send a text through the Ready API outside the recipient's permitted hours, the API can answer 409 with QUIET_HOURS_BLOCK instead of sending. Treat it as a deliberate refusal, not an outage: don't retry in a loop, and either send again once the window opens or resend with hold_until_allowed: true so Ready holds it for you.
The 409 is the API telling you the text was never sent and nothing was charged. How your product reacts decides whether a user sees a clear "we'll send this at 8 AM their time" or a mystery failure. This post shows the exact decision, a handler you can paste, and the words to put in front of the person who pressed send. We make Ready, so the specifics below are Ready's. Other APIs may refuse or queue differently.
What the 409 means
Ready checks the recipient's local time against their permitted texting window before it sends. Campaigns, drip campaigns and automations wait up to 24 hours for that window to open. A text typed in the dashboard or inbox to one person is scheduled for the next allowed time, however far off.
An API text is different. It is held only if the window opens within 6 hours. If the window is further away, the text is not sent and the request returns 409 QUIET_HOURS_BLOCK. You send it again once the window opens, or you ask for a longer hold, covered below.
Two things the 409 is not:
- It isn't a rate limit or a server error, so backoff-and-retry logic written for
429and5xxis the wrong tool. - It isn't a bug in your payload. The same request would have been accepted at 11 AM the recipient's time.
A reply to a contact who texted your account in the last 24 hours goes out at any hour, and that includes an API text, so conversational replies rarely hit this. The 409 mostly appears on first-touch notifications and reminders sent at the wrong hour for the recipient.
The two ways to respond
You have two choices, and which one you want depends on whether the text still matters when it arrives late.
| Option | How | Best for | Watch out for |
|---|---|---|---|
| Send again later | Catch the 409, store the job, retry after the window opens | Texts you want control over, such as a reminder you may cancel | You must work out the recipient's window yourself |
| Hold until allowed | Add "hold_until_allowed": true to the request body | Notifications that are still useful a few hours late | The text goes out on its own, up to 24 hours later |
With hold_until_allowed: true, Ready holds the text for up to 24 hours, the same limit a campaign text gets. A held text is charged only when it sends. If you'd rather decide the send time yourself, POST /sms/schedule takes send_at for one contact, and our post on SMS scheduling, time zones and DST bugs covers the date math.
A handler in TypeScript
This sketch sends one text, keeps one idempotency key per logical message, and sorts the outcome into three results your app code can act on. It reads the response body as text and looks for the error code, so it doesn't depend on any response field names. Check the error reference for the exact body shape.
import { randomUUID } from "node:crypto";
type SendResult =
| { kind: "sent"; body: unknown }
| { kind: "quiet_hours" }
| { kind: "failed"; status: number; detail: string };
export async function sendText(
to: string,
body: string,
idempotencyKey: string,
holdUntilAllowed = false,
): Promise<SendResult> {
const res = await fetch("https://api.tryready.com/v1/messages", {
method: "POST",
headers: {
"X-API-Key": process.env.READY_API_KEY ?? "",
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify({
to,
body,
consent_attested: true,
...(holdUntilAllowed ? { hold_until_allowed: true } : {}),
}),
signal: AbortSignal.timeout(10_000),
});
const text = await res.text();
if (res.ok) {
return { kind: "sent", body: text ? JSON.parse(text) : null };
}
if (res.status === 409 && text.includes("QUIET_HOURS_BLOCK")) {
return { kind: "quiet_hours" };
}
return { kind: "failed", status: res.status, detail: text.slice(0, 500) };
}
// Example caller: try once, then ask for a hold if the user's text can wait.
export async function notifyOrderShipped(to: string, orderId: string) {
const key = randomUUID(); // store this with the job so a retry reuses it
const first = await sendText(to, `Your order #${orderId} has shipped.`, key);
if (first.kind !== "quiet_hours") return first;
// Same body, a different key: the first request was refused, so it is a new attempt.
return sendText(
to,
`Your order #${orderId} has shipped.`,
randomUUID(),
true,
);
} Set consent_attested to true only when the recipient agreed to texts. It's your statement, so it should come from your own consent record, not a hardcoded value. The sample hardcodes it to keep the code short.
Idempotency keys and the second attempt
The Idempotency-Key header exists so a retried request never sends twice. That's the right behavior for a timeout or a dropped connection, where you don't know whether the first call landed. Reuse the same key there.
A 409 is different. The API answered, and nothing was sent. When you decide to resend with hold_until_allowed, treat it as a new attempt. Whether the API replays a stored 409 for a reused key is something to confirm in the docs for your integration. Using a fresh key for a deliberate second request sidesteps the question, as the sample does. Our post on idempotency for SMS APIs explains where a key belongs in the job record.
What to tell the user
The failure mode to avoid is a generic "message failed" toast. The user did nothing wrong, and the text may well go out in a few hours. Pick the message by which path you took.
- You set
hold_until_allowed: "Scheduled. This contact is outside texting hours, so we'll send it when their window opens." - You queued it yourself: "Not sent yet. We'll send it at 8 AM their time tomorrow. You can cancel it until then."
- You decided not to send: "This contact is outside texting hours and the message is time-sensitive, so we didn't send it."
Show the contact's local send time when you know it, and keep the original draft so the user doesn't retype anything. If you hold the text, don't also show a "resend" button for it: a second tap sends a duplicate when the window opens. In the app, Ready's own inbox does the same thing with a held reply, which appears in the thread, so the sender retypes nothing.
Decide before you build the retry
Most teams end up with a small rule table instead of one global policy. Match the rule to the kind of text.
- One-time codes and "your driver is outside" alerts: don't hold them. A late code is worse than none, so fail fast and tell the user.
- Order, appointment and billing notices: use
hold_until_allowed. They're still true in the morning. - Promotions: don't use the API path for these at all. Campaigns already wait for the window and skip recipients whose offer would expire first.
- Anything a user typed one to one: show it as scheduled, not failed.
Keep the 409 count on a dashboard. A steady trickle usually means your product sends from the sender's time zone instead of the recipient's. The legal windows differ by state, and our guide to TCPA calling hours by state lists them, so you can pick the send time before the API has to refuse.
Where to go next
Start with the quickstart at docs.tryready.com/api#quickstart and send one test message. Then trigger the 409 on purpose by texting a number whose local time is outside the window, and confirm your handler tells the user the right thing. Compliance remains the sender's responsibility, so keep your own record of consent and send times alongside whatever Ready holds.