Validation

Meta reviews the template after it is created, but rejects right away anything that is out of shape. The rules below are the ones that show up most, with the error code each one produces.

Whatever the payload structure already states (character limits, accepted types, counts) is declared in the API reference schema: the playground shows it field by field. This page is for the rules the schema cannot express.

Character limits

Field	Limit
Text header	60
Message	1024
Footer	60
Button text	25
Button URL	2000
Button phone number	20
Coupon code	20
Offer text	16
Carousel card text	160
Template name	512

The name accepts lowercase letters, digits and underscore, and it does not change after creation.

Line breaks

Only the message accepts line breaks. Header, footer and button text are single-line: \n, \r and tabs there are grounds for rejection, and so is more than four spaces in a row. In the message, avoid a blank line at the end and more than two breaks in a row.

Variables

By far the biggest source of rejections.

A variable cannot open or close the text

{ "type": "BODY", "text": "{{name}}, your order is on the way" }

{ "type": "BODY", "text": "Hi {{name}}, your order is on the way" }

This applies to the header and to the message. Meta calls it a dangling parameter, and the code is 2388299.

Every variable needs an example

Without example, Meta rejects with missing expected field(s) (example), code 2388043. The example is what the reviewer reads to understand the template.

{
  "type": "BODY",
  "text": "Hi {{name}}, order {{number}} is on the way",
  "example": {
    "body_text_named_params": [
      { "param_name": "name", "example": "Marina" },
      { "param_name": "number", "example": "1042" }
    ]
  }
}

{
  "type": "BODY",
  "text": "Hi {{1}}, order {{2}} is on the way",
  "example": { "body_text": [["Marina", "1042"]] }
}

In positional format, numbering is sequential and starts at 1

The example travels as a list, and Meta matches each item by position. With {{1}} and {{3}}, the third one ends up without an example, and the rejection talks about a missing field without mentioning numbering.

{{1}} with {{3}} is rejected. Use {{1}} and {{2}}.

The header accepts one variable

Just one. The second comes back as “The Header field can only have up to 1 variable(s)”, code 2388029. Meta treats the footer as plain text: a variable there is not replaced and goes literally to the customer.

Short text with many variables is rejected

Meta compares how many variables there are against the length of the text, and rejects what is out of proportion, with code 2388293. It does not publish the formula. From our measurements, with two variables or more, count three words of text per variable, plus one.

{ "text": "text {{a}}{{b}}{{c}}{{d}}. end" }

{ "text": "Hi {{name}}, your order {{number}} goes out for delivery today" }

Two variables glued together, with no text between them, are usually rejected as well.

Buttons

Rule	Limit
Buttons in total	10
URL buttons	2
Phone buttons	1
Copy code buttons	1
Quick replies	10
Buttons per carousel card	2, or 1 on the product card

Quick replies stay together

Meta doesn’t require them to come first: it requires the buttons to sit in two groups, the quick replies and everything else. A quick reply in the middle of other types is rejected.

Accepted	Rejected
quick reply, quick reply	quick reply, URL, quick reply
quick reply, quick reply, URL, phone	URL, quick reply, URL
URL, phone, quick reply, quick reply

URL and phone format

The URL needs http or https. www.yourstore.com without the protocol is rejected, and the error cites the button index in the payload. The phone number goes in international format, with the country code: +5511988881234. Without the + and the country, the rejection is (#192) ... is not a valid phone number.

Variables in buttons

The URL button accepts one variable, and only at the end of the address:

{ "type": "URL", "text": "Track", "url": "https://yourstore.com/order/{{1}}" }

{ "type": "URL", "text": "Track", "url": "https://yourstore.com/{{1}}/order" }

Phone numbers and coupon codes accept no variables.

Labels Meta writes

On catalog, multi-product, single product, checkout, order and on the authentication code, the button text belongs to Meta. The text field is still required: what changes is that the value isn’t yours. Sending a different one is rejected with code 2388153, and the response says which one was right.

Button	`text`
`CATALOG`	`View catalog`
`MPM`	`View items`
`SPM`	`Ver` on a `pt_BR` template, `View` elsewhere
`PAYMENT_REQUEST`	`Review and Pay`
`ORDER_DETAILS`	`Copy Pix code`

There is no language rule here. On the same pt_BR template, Meta demands Ver for SPM and View items, in English, for MPM. Both were measured in rejections. When it rejects, the message states the required text: use that one.

The WhatsApp app translates the label into the recipient’s language, so the value you send at creation is not what the customer reads.

Carousel

2 to 10 cards on the media carousel. On the product one, exactly 2 at creation, and up to 10 at send time.
Every card with the same components. As a consequence: if one card has text, all of them need text; the set of buttons (type and order) is the same across cards. What changes from one card to the next is the button text and the destination.
On the media carousel, every card needs media.
The product card has a {"format": "PRODUCT"} header and a single button, with no card text. Sending two buttons or a body comes back as component of type BODY is required, code 2388045, which does not describe the cause.

Media

Format	Types	Size
Image	JPEG, PNG	5 MB
Video	MP4, 3GPP	16 MB
Document	PDF	100 MB

In the header and in the cards, the media reference is the handle obtained in Upload media, or the public link to the file, which we convert to a handle before creating the template.

The link Meta returns when you read a template (domains whatsapp.net, fbcdn.net, fbsbx.com) is not valid as a sample going back: resent, it is rejected with invalid media sample, code 2388215. This happens in every flow that reads a template and resends what it read.

The link has to open for a server, not only in a browser. Stores and blogs often block automated downloads, and then Meta answers media download failed, code 380. The header image is displayed at 1.91:1, landscape. Anything outside that ratio is not rejected: WhatsApp crops the excess to fit, from the center. Worth building the artwork at that size, or accepting that the edges disappear on the customer’s phone.

Delivery window

message_send_ttl_seconds has a range per category:

Category	Range
Authentication	30 to 900 seconds
Utility	30 to 43200 seconds
Marketing	43200 to 2592000 seconds

The value -1 is a shortcut for 30 days. On authentication, the delivery window cannot be shorter than the code validity: if the message stops being delivered first, the customer loses both.

How many templates fit in the account

The limits below belong to the account, not to the template you are creating. That is why their rejection is confusing: it does not mention anything that is in your payload.

Limit	Value
Templates per WABA	250, or 6,000 with a verified portfolio and a number with an approved display name
Creations per hour, per WABA	100

The name is unique per WABA and language: the same name in pt_BR and in en_US are two templates, and both are accepted. Repeating name and language in the same account comes back as already exists — including when the other one was deleted less than 30 days ago, because deleting reserves the name for that period.

Going over 100 creations per hour is not a payload error: it is a queue. If you are migrating a whole catalog of templates at once, create them in batches and wait between them, instead of retrying right away.

Editing and deleting

An approved template accepts up to 10 edits in 30 days, and one every 24 hours. Rejected and paused have no such cap.
Only approved, rejected and paused templates can be edited.
Name and language do not change. Neither does the category of an approved template.
An edit replaces all components: send the complete set, because whatever is left out is erased.
After an edit, the template goes back into the review queue on its own.
Deleting an approved template reserves its name for 30 days.

Meta errors, and what each one means

Code	Message	What to fix
`2388029`	The Header field can only have up to 1 variable(s)	two variables in the header
`2388043`	missing expected field(s) (example)	variable without an example, or positional numbering out of sequence
`2388045`	component of type BODY is required	body or second button on the product card
`2388153`	Text for button type ‘X’ cannot be modified	fixed label changed
`2388158`	number of buttons exceeded the limit	third button on the limited-time offer
`2388191`	URL is required at index 1	offer without the URL button
`2388193`	Header type TEXT is not allowed	text header on the offer
`2388215`	invalid media sample	Meta CDN link sent back
`2388293`	Parameters words ratio exceeds limit	short text with many variables
`2388299`	Leading or trailing parameters not allowed	variable at the start or at the end
`#192`	is not a valid phone number	phone number without the country code
`380`	media download failed	a link Meta’s server cannot download

When the rejection comes from Meta, we return her original message along with the traceId. Keep both: they are what support uses to identify the case.

Channels

Messages

Templates (WhatsApp)

Flows (WhatsApp)

Webhooks

Character limits

Line breaks

Variables

A variable cannot open or close the text

Every variable needs an example

In positional format, numbering is sequential and starts at 1

The header accepts one variable

The footer accepts no variables

Short text with many variables is rejected

Buttons

Quick replies stay together

URL and phone format

Variables in buttons

Labels Meta writes

Carousel

Media

Delivery window

How many templates fit in the account

Editing and deleting

Meta errors, and what each one means

​Character limits

​Line breaks

​Variables

​A variable cannot open or close the text

​Every variable needs an example

​In positional format, numbering is sequential and starts at 1

​The header accepts one variable

​The footer accepts no variables

​Short text with many variables is rejected

​Buttons

​Quick replies stay together

​URL and phone format

​Variables in buttons

​Labels Meta writes

​Carousel

​Media

​Delivery window

​How many templates fit in the account

​Editing and deleting

​Meta errors, and what each one means

Character limits

Line breaks

Variables

A variable cannot open or close the text

Every variable needs an example

In positional format, numbering is sequential and starts at 1

The header accepts one variable

The footer accepts no variables

Short text with many variables is rejected

Buttons

Quick replies stay together

URL and phone format

Variables in buttons

Labels Meta writes

Carousel

Media

Delivery window

How many templates fit in the account

Editing and deleting

Meta errors, and what each one means