When Flow refuses a request it says why in plain words, and a refused request sends nothing.
Read the status first: only 429 and the 500s are worth retrying automatically. Everything else needs a change on your side, and the message says which.
In review: written from the product, not yet walked through live.
1400 — something in the request
Flow’s own checks name the field: “to required”, “template_name required”, “variables must be a flat list of values” (1, 2), “callback_data must be 512 characters or fewer”. WhatsApp’s refusals come back as 400 too, in WhatsApp’s words — a template that isn’t approved, too few or too many values, a wrong language.
"reason": "window_closed" means free text outside the 24-hour window: send a template.
2401 — the key, or a hook’s proof
“Valid API key required”: the key is missing, mistyped or revoked. Check the header reads exactly
Authorization: Bearer sk_flow_…, with one space after Bearer; lost or revoked, create a new key. On an inbound hook, 401 means the caller’s secret, password or signature is wrong — the message says which (how hooks check).3402 — the wallet
“Your messaging wallet is empty — top it up to send.” Nothing was sent. The same answer comes when the workspace reaches its daily spending limit. Top up and sending works again at once. Have your system alert a person on
402, so messages never stop without anyone noticing.4403 — a permission, or a feature that’s off
The message names the permission the key lacks (1), such as
contacts:read — create a key with that box ticked. “The Flow API is not enabled for this account yet” or “Inbound hooks are not enabled for this account yet” means the Developers tools are switched off for your workspace — message us. For one-time codes, otp_disabled means OTP is off in Settings.
5404 — not in your workspace
“Contact not found” or “Conversation not found”: the id doesn’t exist in the workspace the key belongs to. Use an id your own key listed. A hook address that was deleted answers
404 too.6409 — no WhatsApp number to send from
The workspace has no connected WhatsApp number (1). Connect one in Settings → Channels, or reconnect it if it shows as disconnected.
7413 and 422 — too big, or not allowed
413: an inbound hook’s body was over 256 KB — send less. 422: the customer opted out of your messages (“This contact has opted out of messages from you.”), or an inbound hook’s own rule refused the call. Don’t retry.
8429 — slow down
Only one-time codes and inbound hooks have limits of their own: an OTP limit (
rate_limited), a hook’s 300 calls a minute, or the daily cap you set on a hook (1). Wait, then retry with a longer gap each time; if the traffic is real, raise the hook’s cap.
9The 500s — our side
A
500, 502 or 503 is a fault on our side or WhatsApp’s. Retry after a short wait, then longer. If it keeps happening, message us with the time and the request you sent.© 2026 SkedX · Sample data only · Share and link freely · Copying the product or its design is not allowed · Terms
Common questions
Which errors should my code retry?
Only
429 and the 500s — waiting a little longer each time (for example 5 s, 30 s, 2 min). Every other error will fail the same way again until something changes.Is anything charged when a request fails?
Flow’s own checks — a 401, 402, 403, 404 or 409, and the 400s that name a field — happen before anything is sent. For one-time codes, a code that can’t be delivered is refunded.
The error text isn’t English I recognise.
A 400 that doesn’t look like Flow’s own messages is WhatsApp’s explanation, passed through as it came. The most common: a template name that isn’t approved on your number, or the wrong number of values.
Next in APIs & DevelopersSend WhatsApp templates without code, using an inbound hook →
Useful links
- Flow API reference — every request’s possible answers
- Wallet in Flow — for 402
- Channels in Flow — for 409
Previous: Send and check one-time codes (OTP) · All APIs & Developers guides
Did this guide help?
Still stuck?Chat with support →
