​

Troubleshooting: WhatsApp template pending, rejected, or blocked by the 24h window

​

Template sync fails with TEMPLATE_SYNC_FAILED (400)

​

Cause family

• OAuth token expired or re-scoped. The stored Meta token from Embedded Sign-up lapsed, or Meta revoked a permission the sync needs before it can page the template list.
• IP-allowlist mismatch on the tenant credential. If your WABA credential carries an allowlist in Meta’s app settings, Meta Graph rejects calls from addresses that are not on it.
• WABA in a non-billable or locked state. An account under Meta enforcement, a missing payment method, or a disabled WABA refuses template reads before any template verdict applies.
• Meta Graph transient 5xx. Meta’s own API had a bad moment; the rejection has your side in a healthy state.

​

Decision procedure

1. Re-check the connection state and brand quality. Read GET /api/v1/whatsapp/connections and confirm the WABA reports connected with no quality downgrade. A locked or restricted WABA fails every Meta Graph call, not just the sync — work Troubleshoot the WhatsApp connection first when the connection itself is red.
2. Confirm the WABA credential set. Open Settings → Channels → WhatsApp and verify the stored credential still matches what Meta Business Manager shows for the WABA. If the OAuth grant expired or Meta re-scoped the permissions, re-run the connect flow from the same screen — the procedure and the token-family split are in WhatsApp re-authentication and Embedded Sign-up recovery.
3. Retry the sync once after the cause is fixed. The sync is idempotent and safe to re-run, but never loop the same 400 — a deterministic rejection at Meta does not clear on repetition. If two consecutive fixed-and-retried attempts fail the same way, escalate with the payload at the bottom of this page.

​

Symptom map

​

How to inspect a template

curl -G "https://api.orbit.devotel.io/api/v1/messages/templates" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  --data-urlencode "search=order_shipped" \
  --data-urlencode "channel=whatsapp"

• status — the local view of Meta’s verdict: pending_review, approved, rejected, paused, disabled, or submission_failed (Meta refused the create call itself — the request never became a template at their side).
• metadata.rejection_reason — Meta’s own words for a rejection. This is the single most useful field on the page: it names the policy clause or formatting error Meta acted on.
• external_id — Meta’s template id, present only after a successful submission. A missing external_id means the row has never been accepted by Meta.

​

Fix workflow per status

• pending — let it run. Approval lands in minutes for utility and authentication templates. Marketing templates take longer. Do not resubmit while the first attempt is in flight — the two submissions compete for the same review slot.
• rejected — edit and resubmit. Read metadata.rejection_reason, fix the named problem, and PATCH the template. Editing clears the way for resubmission, and Meta keeps the template name free for 30 days, so you do not need to rename. Reassign the category in the same edit if the rejection was a category mismatch.
• submission_failed — fix the account, then resubmit. Meta refused the submission call: a WABA permission missing, the account under feature review, or an app-config problem. Nothing was created at Meta’s side, so the template body is usually fine. Verify the WABA state in Meta Business Manager, then resubmit.
• Misclassified — resubmit with the category change. If a utility template kept coming back as marketing, its body reads as promotional. Rewrite the body so it only covers the order, booking, or account event, then resubmit as utility. Accepting marketing pricing is the cheaper fix when the content is genuinely promotional.
• Sampling-limited — add a real opt-in example. When Meta asks for sample traffic, submit a screenshot or example from a real opted-in conversation rather than a fabricated one — a built-up example that never matched real traffic is one of the most common second-rejection causes.
• Re-review window — wait. After a resubmission, a fresh review cycle starts. The status field and webhook events move again when Meta answers; the fix workflow from there is the same as for a new template.

​

What not to do

• Do not spam POST /templates with the same body. Meta rate-limits duplicate submissions per WABA, and a rejected body resubmitted unchanged earns faster rejections. Every submission should fix what the rejection reason named.
• Do not switch the category without adjusting the variables. A utility template that names a discount in {{1}} becomes a marketing template with the category flag flipped and nothing else changed — Meta’s reviewers catch that immediately, and so does the automatic reclassification later.
• Do not reuse a rejected name immediately on a brand-new template. The 30-day name hold exists so the same name can be fixed in place. Deleting a rejected template and recreating it under the same name inside the hold window trips the duplicate-name throttle and delays the resubmission.
• Do not test a rejected template with production traffic. A send against a non-approved template fails before it reaches Meta, and the failures count against your WABA’s quality metrics.

​

Escalation payload

1. Your WABA id (Meta Business Manager → WhatsApp Manager, or the waba_id on any template record).
2. The template name + language exactly as Meta has them (order_shipped + en_US, not a display label).
3. The rejection code or reason from metadata.rejection_reason, or the details.reason from the whatsapp.template.rejected webhook event.

​

See also

• WhatsApp 24h freeform window — when a template send is required, the pre-flight window check, and the error codes that mean “send a template”.
• WhatsApp content policy — the prohibited and restricted categories every rejection reason maps back to.
• Templates API — the create/read/update contract for every endpoint this page uses.
• Troubleshoot WhatsApp Flow submissions — the submissions/CDP layer playbook for Flow sends that went through.
• WhatsApp Meta Policy Cadence — Meta-side enforcement shifts such as template-category migration, per-user marketing caps, and regional pause experiments.
• Troubleshoot the WhatsApp connection — distinguish a locked WABA (WHATSAPP_ACCOUNT_LOCKED, Meta 131031 — account-level enforcement) from template-level failures: an account lock fails every send, including submissions.
• WABA setup — first-time submission flow and the approval-timelines table.
• Webhook events — the whatsapp.template.* events for driving this workflow from your own systems.