> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot template rejection: TEMPLATE_REJECTED and WHATSAPP_TEMPLATE_REJECTED

> Decode Orbit's two template-rejection codes, read the rejection reason in details.reason, fix the template on your side, and resubmit it for review.

# Troubleshoot template rejection (Orbit codes)

A WhatsApp template call fails with one of Orbit's own rejection
codes. Either the create call returns 422
`WHATSAPP_TEMPLATE_REJECTED` because the carrier rejected the
submission, or a send returns 422 `TEMPLATE_REJECTED` because the
stored template's review status is `rejected` and Orbit refuses the
send before Meta is reached. Both are deterministic: the template
itself is the problem, and re-sending the unchanged payload replays
the same 422 until the template changes. This page decodes which code
you got, reads the reason, and walks the fix-and-resubmit path.

> [!NOTE]
>
> Meta's numeric codes (132001, 132016, 132068, 133010 and the
> rest) live on their own page:
> [Troubleshoot WhatsApp template lifecycle errors](https://docs.orbit.devotel.io/troubleshooting/whatsapp-template-lifecycle-errors.md).
> If your error carries `details.whatsappErrorCode` instead of the two
> codes below, start there. That page covers Meta's refusals; this
> page covers Orbit's; each links to the other.

## Which rejection code you got

| Code | Where it fires | What it means | First move |
| - | - | - | - |
| `WHATSAPP_TEMPLATE_REJECTED` | 422 on template create (`POST /api/v1/messages/templates`) | The carrier rejected this submission. The envelope carries `details.reason` naming the rejection class. | Read the reason table below, fix the template, resubmit |
| `TEMPLATE_REJECTED` | 422 on send, from Orbit's preflight | The stored template's review status is `rejected`, so Orbit blocks the send before Meta is reached | Read the verdict below, fix and resubmit, then send again |
| Meta numeric codes (132001, 132016, 132068, …) | `failed` delivery, `message.failed` webhook | Meta refused the send for template or account state | [Troubleshoot WhatsApp template lifecycle errors](https://docs.orbit.devotel.io/troubleshooting/whatsapp-template-lifecycle-errors.md) |

The two Orbit codes are the same underlying fact seen at two moments:
`WHATSAPP_TEMPLATE_REJECTED` tells you at submission time that the
carrier rejected the template; `TEMPLATE_REJECTED` enforces that
rejection later, on every send through the stored template. If you
see the send-side code, the create-side rejection already happened,
and the reason it gave is still the one to fix.

## What `details.reason` tells you

The create 422 envelope carries a stable reason string in
`details.reason` plus the request id you will want if this ends up at
support:

```json theme={null}
{
  "error": {
    "code": "WHATSAPP_TEMPLATE_REJECTED",
    "message": "The carrier rejected this template",
    "status": 422,
    "details": {"reason": "PROMOTIONAL_LANGUAGE_NOT_ALLOWED"}
  },
  "meta": {
    "request_id": "req_tpl_rejected",
    "timestamp": "2026-08-01T12:03:00.000Z"
  }
}
```

Every reason names something inside the template, so every fix is a
template edit on your side: rewrite the copy, change the category, or
adjust the media. A rejection is never cleared by resending the same
payload.

| `details.reason` | What it means | Your fix |
| - | - | - |
| `PROMOTIONAL_LANGUAGE_NOT_ALLOWED` | The copy uses promotional language (sales pitches, urgency, exclamation-styled calls to action) that the template's category or the target market does not allow. | Rewrite the body without the promotional language, or move the content into a MARKETING-category template where promotional copy belongs. Check the market's promotional-language rules before you resubmit. |

Read `message` alongside `details.reason`: the reason names the
rejection class, and the message quotes the concrete problem in your
submission (it may echo the offending text). Fix what the message
points at, not just what the reason class suggests.

## Read the verdict

The rejection reason and the current review status stay attached to
the template record after the 422 is long gone from your logs:

* **API.** The template record returned by the templates endpoints
  carries the review status (`pending`, `approved`, `rejected`) and,
  when rejected, the reason from the last review. A `TEMPLATE_REJECTED`
  send 422 means that record currently reads `rejected`.
* **Dashboard.** Open the template library and select the template:
  the detail view shows the review status and the rejection reason,
  the same values the API returns.
* **Meta's side.** Review typically completes within 24 hours, and a
  rejected template can sit in `rejected` until you act. The pending
  and rejected review states and the review window are covered in
  [Troubleshoot WhatsApp templates](https://docs.orbit.devotel.io/troubleshooting/whatsapp-template.md).

## Edit and resubmit

1. Read the verdict above and note the reason.
2. Make the fix in the template itself: rewrite the copy, change the
   category (utility content in a MARKETING template, or promotional
   content in a UTILITY template, will keep getting rejected), or
   adjust the media.
3. Resubmit for review from the template's detail view in the
   dashboard, or submit the corrected template through the templates
   API.
4. Watch the review status return to `pending`, then `approved`.

Resubmission does not restore approval for live traffic. While the
resubmission is `pending`, the old rejected verdict is gone but no
new approval exists, and sends remain blocked or refused exactly as
before. Meta reviews the new submission from scratch; approval is
what re-opens the template for live traffic, not the act of
resubmitting.

### Worked example

A create call for a utility template whose body reads like an
advertisement:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/messages/templates" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"order_ready","channel":"whatsapp","language":"en_US","category":"UTILITY","components":[{"type":"BODY","text":"Buy now!!!"}]}'
```

returns the 422 shown in the reason table above:
`WHATSAPP_TEMPLATE_REJECTED` with
`details.reason: "PROMOTIONAL_LANGUAGE_NOT_ALLOWED"`. Decode it: the
body is promotional copy submitted under the UTILITY category. Fix it
on your side, either rewrite the body to plain order-ready wording or
move the promotional copy into a MARKETING template, then resubmit.
The corrected create returns 201 with the template record at status
`pending`, and once review flips it to `approved`, sends through it
pass the preflight that previously returned `TEMPLATE_REJECTED`.

## Fix vs retry, one rule

Retry never clears a rejection. Both codes are deterministic refusals
about template state, so Orbit does not retry them automatically, and
a manual re-send of the unchanged payload reproduces the same 422.
Fix the template first, then send again; that send is a new request,
not a retry. The same rule governs Meta's numeric codes on
[Troubleshoot WhatsApp template lifecycle errors](https://docs.orbit.devotel.io/troubleshooting/whatsapp-template-lifecycle-errors.md);
the only retriable family in WhatsApp sending is transient platform
faults, which are covered there.

## What to send support

If you have fixed the template and resubmitted and rejections
continue, email
[whatsapp-support@devotel.io](mailto:whatsapp-support@devotel.io)
with:

1. The **template id** and the template name and language exactly as
   configured (`order_ready` + `en_US`).
2. The **`details.reason`** value from the 422, or the rejection
   reason shown on the template record.
3. The **`request_id`** from the error envelope's `meta` block.
4. The **timestamp** of the failing create or send.

With the request id and the reason, support can show you exactly what
the carrier reported for that submission; the template edit itself
stays on your side.

## See also

* [Troubleshoot WhatsApp template lifecycle errors](https://docs.orbit.devotel.io/troubleshooting/whatsapp-template-lifecycle-errors.md) —
  the Meta numeric codes (132001, 132016, 132068, 133010, …).
* [Troubleshoot WhatsApp templates](https://docs.orbit.devotel.io/troubleshooting/whatsapp-template.md) —
  pending and rejected review states and the 24-hour review window.
* [Troubleshoot WHATSAPP\_TEMPLATE\_VAR\_COUNT\_MISMATCH](https://docs.orbit.devotel.io/troubleshooting/whatsapp-template-var-count.md) —
  the send-side parameter pre-flight that refuses before Meta is
  reached.
* [WhatsApp channel overview](https://docs.orbit.devotel.io/channels/whatsapp.md) — setup and the
  connection model.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.