Errors
{"success": false, "request_id", "error": {"code", "message", "how_to_fix", ...}} · decide by error.code
Envelope
- success booleane.g.
false - request_id string
Quote this when contacting support.
e.g.kxrkf - error object
9 fields
-
Stable error code, safe to use in your own logic.
account_deactivatedaccount_not_confirmedaccount_service_erroraccount_service_unavailableapi_key_expiredapi_key_number_mismatchapi_key_old_formatapi_key_revokedapproval_already_resolvedapproval_body_too_largeapproval_expiredapproval_not_foundautomation_not_foundbackground_start_failedblock_list_busyblock_list_fullblock_not_foundblock_users_errorblock_users_failedbooking_cancelledbooking_not_enabledbooking_not_foundbooking_slot_takenbroadcast_cancelledbroadcast_not_cancellablebroadcast_not_foundbsuid_not_supportedcall_permission_requiredcaption_not_supportedcaption_too_longcatcher_not_foundclient_existsclient_not_editableclient_not_foundconnection_failedconnection_in_useconnection_not_foundcontact_book_errorcontact_not_foundconversation_not_found -
What is wrong, in plain words.
-
What to change to make the request work.
- documentation_url string
Where this error is explained.
e.g.https://www.app2email.com/docs/api/errors#template_not_found - is_retriable boolean
true: the same request can work later without a change (limits, caps, trouble on our side or WhatsApp's, a request with the same Idempotency-Key still running).
- retry_after_seconds integer
How long to wait before trying again, when known (also the Retry-After header).
-
Extra information, eg the problems found, available templates or languages.
- example_request object
A WhatsApp message in the format of WhatsApp Cloud API (Meta's exact body works unchanged): a template (type 'template', the default, any time), or within 24 hours of the contact's last message a free-form text, image, video, document, audio, sticker, location, contacts, reaction or interactive message. Meta's mark-read body {messaging_product, status: 'read', message_id, typing_indicator?} marks a message as read. Give 'to' or 'recipients' (templates only).
- whatsapp_error object
WhatsApp's (Meta's) own error, when the error came from WhatsApp.
5 fields
- code integere.g.
132000 - message string
- details string
- type string
- fbtrace_id string
-
| error.code | HTTP | Meaning | How to fix |
|---|---|---|---|
| caption_not_supported | 400 | WhatsApp does not show a caption on an audio message. | Leave "caption" out, or send the text as its own message. |
| duplicate_recipients | 400 | Some numbers are in "recipients" more than once, listed in details.duplicates. Nothing was sent. | List each number once. (With "recipients" each number can have its own values, so we do not guess which entry you meant.) |
| free_form_single_recipient | 400 | A "…" message goes to one number. "recipients", "background" and "send_at" are for template messages. | Send one request per contact, or use a template to message many numbers. |
| invalid_addons | 400 | addons is a comma list of the service's add-on ids (services[].addons), or leave it out. | |
| invalid_analytics_query | 400 | 'granularity' must be half_hour, day or month. | Use eg granularity=day. |
| invalid_answers | 400 | Answer every required question of the service. | |
| invalid_auth_template | 400 | The authentication template request is not valid: its languages, otp_type or components. | See example_request: languages and an otp_type, or WhatsApp's own components. |
| invalid_automation | 400 | An automation is not valid: an unknown trigger or action type, a missing key, a rule or formula that cannot be read, or a form, stage, member or connection that does not exist. | Fix each problem in error.details. GET /submit/guide lists the triggers and the actions with their keys. |
| invalid_block | 400 | A time block is not valid: the end is not after the start, it is longer than 31 days, the staff member does not exist, or a text is too long. | Fix the fields named in the message. Give start and end (or date for a whole day); provider_id is one of GET /bookings/staff, or left out for everyone. |
| invalid_booking | 400 | Give the Flow a name. | { action: create | duplicate | delete | set_default | update, key, name?, kind?, from?, trigger_keywords?, enabled? } |
| invalid_bsuid | 400 | '…' is not a business-scoped user id (country code, a dot, letters and digits, eg US.13491208655302741918). Parent ids (with.ENT.) are not in the contact book. | Use from_user_id of a message.received event. |
| invalid_call_request | 400 | Nothing was sent to WhatsApp: …. | Send eg {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. |
| invalid_call_settings | 400 | 'calling' must be an object. | Send eg {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. |
| invalid_callback_data | 400 | "callback_data" is … characters. WhatsApp allows up to …. | Send a short reference (eg your order id) and keep the rest on your side. |
| invalid_catalog_id | 400 | 'catalog_id' must be the catalog's id from Commerce Manager (digits). | Send eg {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. |
| invalid_client_request | 400 | A field of the client request is not valid (eg "name" or "send_invite"). | Example: {"email": "ann@example.com", "name": "Ann's Bakery"}. |
| invalid_compare_days | 400 | ?days= must be 7, 30, 60 or 90. | Leave it out for 30. |
| invalid_compliance_info | 400 | Nothing was changed: …. | Send eg {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. |
| invalid_components | 400 | "template.components" must be an array. | See example_request. |
| invalid_connection | 400 | A connection is not valid: the address is not https or points at a private address, the kind or the sign-in type is unknown, a header may not be set, or the OpenAPI document cannot be read. | Fix each problem in error.details. Only OpenAPI 3.0 / 3.1 documents in JSON and MCP servers on streamable HTTP are read. |
| invalid_contact_email | 400 | The e-mail address is missing or not an e-mail address. | Send eg "contact_email": "ann@example.com". |
| invalid_contacts | 400 | Nothing to change: give "tags". | Send one contact {"phone": "61412345678", "name": "John", "tags": ["vip"], "custom_fields": {"order_id": "1234"}, "consent": {"marketing": true, "source": "web form"}} or a list of them (up to 1000). |
| invalid_contacts_message | 400 | "contacts" must list 1 to … contact cards. | Each card: {"name": {"formatted_name": "Jane Citizen"}, "phones": [{"phone": "+61 412 345 678", "type": "CELL"}]}. |
| invalid_conversation_starters | 400 | Nothing was changed: …. | Send eg {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. |
| invalid_conversion_events | 400 | Nothing was sent: …. | Send eg {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. |
| invalid_coupon | 400 | The coupon cannot be used: unknown, for another service, expired, used up or switched off. | Check the code in config.payments.coupons, or leave coupon out. |
| invalid_csv | 400 | The CSV needs a header row and at least one contact row. | Send text/csv with a header row (phone,name,tags,consent_marketing,consent_source,consent_text,consent_evidence,consent_at,source and any custom field columns; tags separated by |), or application/json with a list of contacts as for POST /contacts. Up to 5000 rows. |
| invalid_cursor | 400 | The cursor is not valid. | Pass the next_cursor of the previous answer unchanged, or leave cursor out for the first page. |
| invalid_direction | 400 | "direction" must be in or out. Got: '…'. | Leave it out for both. |
| invalid_display_name | 400 | "name" must be 3 to 512 characters on one line. | Send {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. Meta's display name guidelines: https://www.facebook.com/business/help/757569725593362 |
| invalid_estimate | 400 | A value of the cost estimate is missing or not a number. | eg /v1/account/estimate?messages_per_month=5000 ; Meta's fees: marketing=3000&rate_marketing=0.025. |
| invalid_event_type | 400 | "types" names an event type that does not exist. | Use the event types of https://www.app2email.com/docs/api/webhooks, comma separated. Left out: every event. |
| invalid_events | 400 | Unknown event type '…'. | Use one of: …. |
| invalid_flow_categories | 400 | "categories" must be a list with at least one of: …. | eg ["APPOINTMENT_BOOKING"]. |
| invalid_flow_field | 400 | "publish" must be true or false. | Fields: name, categories, flow_json, publish, endpoint_uri, clone_flow_id. |
| invalid_flow_id | 400 | A flow id is a number, eg 1234567890123456. Got: '…'. | GET /v1/…/flows lists them. |
| invalid_flow_json | 400 | "flow_json" …. | See example_request and WhatsApp's Flow JSON reference. |
| invalid_flow_name | 400 | "name" must be 1 to 200 characters (customers do not see it). | eg "appointment_booking". |
| invalid_form | 400 | A form or its definition is not valid. error.details lists every problem as {path, code, message, fix}; the path looks like definition.steps[1].fields[2].pattern. | Fix each problem at its path and send the form again. GET /submit/guide explains every key and limit. |
| invalid_guests | 400 | 'seats' must be a whole number from 1 to 200. | seats: the places wanted on a group time (1 + guests). Leave it out for 1. |
| invalid_idempotency_key | 400 | The Idempotency-Key header must be 1 to … printable ASCII characters. | Use a new random value (eg a UUID) for each message or list you send, and send the same value again only when you retry that same request. |
| invalid_identity_key_hash | 400 | "recipient_identity_key_hash" is one contact's: the request has … recipients. | Send it with one recipient, or per number in "recipients": [{"to": "61412345678", "recipient_identity_key_hash": "..."}]. |
| invalid_insights_request | 400 | ?templates= must name 1 to 10 templates, comma separated. | eg ?templates=order_update,summer_sale. |
| invalid_interactive | 400 | "interactive" is not valid: its type, a text length, the buttons or the rows. | button: up to 3 reply buttons. list: a menu of up to 10 rows. cta_url: one button that opens a URL. carousel: 2 to 10 cards. |
| invalid_json | 400 | The request body is not valid JSON, or not a JSON object. | Check for missing quotes, commas or brackets near the position given (LineNumber / BytePositionInLine). A JSON validator helps. |
| invalid_keep_old_for_hours | 400 | "keep_old_for_hours" must be a whole number from 0 to …. | 0 (or leave it out): the old secret stops at once. 24: events are signed with both secrets for 24 hours. |
| invalid_key_request | 400 | A field of the key request is not valid: name (1 to 60 characters), scopes, sandbox or expiry (1 to 365 days). | details lists the permissions there are. |
| invalid_library_filter | 400 | ?…= is longer than 200 characters. | Use a shorter value. |
| invalid_limit | 400 | 'limit' must be a whole number from 1 to 100. | Use limit=1 to limit=100. |
| invalid_link | 400 | A booking link cannot be made or changed like that: an unknown purpose, service or staff member, a reschedule or manage link without a customer, expires_in_hours outside 1 to 1440, or a public address revoked as a link. | Fix the fields named in the message. |
| invalid_list | 400 | A list is not valid: no name, an item without an id or a title, two items with the same id, more than 1,000 items or more than 200 KB. | Send {name, items: [{id, title, ...}]} with unique ids. |
| invalid_location | 400 | "location" is required: {"latitude":.., "longitude":.., "name"?, "address"?}. | See example_request. |
| invalid_marketing_api | 400 | "marketing_api" must be "auto", "cloud_api" or "mm_api" (or true / false). | Leave it out to use the number's setting messages.marketing_route (GET /settings/number). |
| invalid_media_id | 400 | '…' is not a WhatsApp media id (digits, eg the media_id of POST /media). | app2email's stored copies of received files are not deleted through this call. |
| invalid_media_type | 400 | "type" must be image, video, document, audio or sticker. | Or leave it out: the kind is taken from the file. |
| invalid_member | 400 | A member cannot be saved: the e-mail address is missing or wrong, it is a member already, the team is full, the role or an ability is unknown, a form key does not exist, nothing to change was sent, or the owner's own row would be changed or removed. | Roles: admin, manager, agent, viewer. GET /submit/guide lists the abilities. |
| invalid_months | 400 | 'months' must be a whole number from 1 to …. Got: '…'. | Use months=1 to months=…. The default is …. |
| invalid_note | 400 | A note is not valid: it is empty or over 4000 characters, or it has neither a contact nor a booking_id. | Send a body of 1 to 4000 characters and a contact or a booking_id. |
| invalid_number | 400 | A number is not a full phone number. | Give the number with its country code, digits only, eg 61412345678. |
| invalid_number_in_url | 400 | The URL must contain the full WhatsApp number you send from, digits only (country code first). Got: '…'. | Use your app2email WhatsApp number without '+', spaces or dashes, eg: https://api.app2email.com/v1/61412345678/messages |
| invalid_numbers | 400 | … of the numbers are not valid, listed in details.invalid. Nothing was added. | Write each number with its country code, digits only, eg 61412345678 for +61 412 345 678. |
| invalid_oba_request | 400 | The request was not sent: …. | Send eg {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. |
| invalid_onboarding_request | 400 | A field of the onboarding link request is not valid (eg "state" over 200 characters). | "state" comes back unchanged in the redirect, eg "crm-lead-4711". |
| invalid_optimization_spec | 400 | "optimization_spec" …. | Max price per 1,000 deliveries: {"bid_amount": 5000, "bid_strategy": "LOWEST_COST_WITH_BID_CAP"} (5000 = USD 0.05 a message in cents x 1,000). Both null to go back to the rate card. |
| invalid_owner | 400 | "owner" must be one of: "" (normal routing), agent, human, paused. Got: '…'. | Send {"owner": "human", "reason": "customer asked for a person", "summary": "wants to change the delivery date", "until_minutes": 120}. owner: "" (normal routing), agent, human or paused. The other fields are optional. |
| invalid_partner_settings | 400 | A partner setting is not valid (eg "trial"). | A trial has 10 to 10000000 messages and lasts 1 to 365 days: {"trial": {"enabled": true, "messages": 50, "days": 14}}. |
| invalid_payment | 400 | A payment request is not valid: the amount is missing or not above 0, a session count is out of range, or a booking has no amount to mark as due. | Fix the field named in the message. |
| invalid_phone | 400 | The contact in the URL is not a phone number or a business-scoped user id. | Use the contact's full number, country code first (eg .../contacts/61412345678), or their business-scoped user id. |
| invalid_plan | 400 | "plan" is missing or not a plan that can be chosen, or "yearly" is not true or false. | Use a plan id from list_plans (GET /v1/account/plans), eg "standard_5000". |
| invalid_poll | 400 | A meeting poll is not valid: no title, fewer than 2 or more than 10 options, an option that is not a time, no service or length, or a vote on a closed poll. | Fix the field named in the message. |
| invalid_profile | 400 | The profile was not changed: …. | Send only the fields to change, eg {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. |
| invalid_public_key | 400 | "public_key" is missing. | Make a key pair: openssl genrsa -out private.pem 2048; openssl rsa -in private.pem -pubout -out public.pem. Send the text of public.pem as {"public_key": "-----BEGIN PUBLIC KEY-----\n..."}. |
| invalid_qr_code | 400 | No QR code was made: 'image' must be svg or png. | Send eg {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. |
| invalid_range | 400 | 'since' must be before 'until' (and before now). | Use eg since=2026-10-01T00:00:00Z&until=2026-11-01T00:00:00Z. |
| invalid_reaction | 400 | "reaction" is required: {"message_id": "wamid...", "emoji": "..."}. | See example_request. |
| invalid_recipients | 400 | "recipients" must be a list with at least one entry. | "recipients" is a list of objects, one per number: [{"to": "61412345678", "components": [{"type": "body", "parameters": [{"type": "text", "text": "John"}]}]},...]. "components" holds only what differs for that number; the rest comes from template.components. |
| invalid_redirect_url | 400 | "redirect_url" is not a full https:// address of at most 500 characters. | Example: "https://crm.example.com/whatsapp/connected"; null removes it. |
| invalid_reply_to | 400 | "reply_to" must be the message_id of one of the contact's messages (it starts with 'wamid.'). | {"text": "..."} or {"media": {"data": "<base64>", "filename": "photo.jpg", "mime": "image/jpeg"}, "text": "caption"} or {"template": {"name": "...", "language": "en", "body_params": ["..."]}}, each with "sender": {"name", "email"}. |
| invalid_segment | 400 | "name" must be 1 to 100 characters and not just a number. | Send {"name": "VIP, consented", "filter": {"tags_any": ["vip"], "consent_marketing": true, "last_inbound_days": 90}}. |
| invalid_send_at | 400 | "send_at" is not a valid time with a time zone: '…'. | Use an ISO 8601 time with its time zone, eg "2026-11-02T09:00:00+11:00" or "2026-11-02T09:00:00Z", between 1 minute and 29 days from now. |
| invalid_series | 400 | Pick how often and how many times, as the service offers it. | |
| invalid_service | 400 | "service_id" is missing. | service_id is one of config.services[].id (switched on). |
| invalid_setting | 400 | 'name' is over 200 characters. | Use a shorter name, or leave it out. |
| invalid_settings | 400 | A Submit-Info setting is not valid: a prefix that is not 2 to 4 letters, too many menu or status words, a colour that is not #RRGGBB, an unknown time zone, or a retention time out of range. | Fix each problem in error.details. GET /submit/settings shows every key with its value. |
| invalid_setup | 400 | The setup document has problems, so nothing was written. error.details lists every problem with its path in the document. | Fix them and send the document again. With dry_run true the problems are listed and nothing is changed. |
| invalid_slug | 400 | The public address (slug) is not valid: 3 to 40 characters of a-z, 0-9 and '-', not a reserved word. | Choose another address. |
| invalid_start | 400 | "start" is missing. | start is yyyy-MM-ddTHH:mm in the business time zone, one of the slot ids of GET.../bookings/availability. |
| invalid_status | 400 | "status" must be pending or all. | Example: GET.../approvals?status=all |
| invalid_submission | 400 | A submission, a change to one, a note, a reply or a list filter is not valid: an answer is missing, of the wrong type or out of range, the form is archived, the stage, assignee or priority is unknown, a text is empty or too long, or a file cannot be read. | error.details names each field. GET /submit/forms/{key} lists the form's fields and stages. |
| invalid_template_category | 400 | "category" must be one of: …. | UTILITY for order and account updates, MARKETING for promotions, AUTHENTICATION for one-time codes. WhatsApp may change the category if it disagrees. |
| invalid_template_components | 400 | "components" must be a list of objects that each have a "type" (HEADER, BODY, FOOTER, BUTTONS). | See example_request. Components are in WhatsApp's own format. A Template Library template takes library_template_name instead. |
| invalid_template_field | 400 | These fields cannot be changed: …. | Send it as WhatsApp's template API takes it, or leave it out. |
| invalid_template_ids | 400 | Give "names" (template names: every language of each) or "ids" (WhatsApp template ids: one language each), not both. | eg {"names": ["old_promo", "summer_sale"]}. |
| invalid_template_language | 400 | ?language= must be a WhatsApp language code like en or en_US. | See WhatsApp's list of supported template languages. |
| invalid_template_name | 400 | "names" must be template names: lower case letters, digits and underscores. | eg "order_update". |
| invalid_template_preview | 400 | ?languages= must be up to 60 WhatsApp language codes, comma separated (eg en_US,es_ES). | Leave it out for every language. |
| invalid_test_event | 400 | "event" must be a JSON object. | Send nothing for a ping, {"type": "message.received"} for that event's sample (GET.../webhooks/samples), or {"event": {"type": "message.received", "data": {...}}} to send your own. |
| invalid_text | 400 | "text" must be 1 to … characters. | Send {"text": "Thanks for writing! We reply within a day."} (1 to 4000 characters). |
| invalid_ticket_check_in | 400 | The check-in request is not valid. | Send {"code": "<the text of the QR code>", "date_id": 31} or {"ticket_id": 501}. |
| invalid_ticket_code | 400 | The promo code is not valid. | A code is 3 to 20 characters of A-Z, 0-9, _ and -. kind percent takes 1 to 100; kind amount takes an amount in the code's currency. |
| invalid_ticket_event | 400 | The event, date or ticket type is not valid. | Fix the field named in the message. GET /tickets/events/{id} shows the stored values. |
| invalid_ticket_order | 400 | The order is not valid. | Fix the field named in the message. GET /tickets/events/{id}/availability lists the ticket types with their ids, prices and limits. |
| invalid_time | 400 | 'from' is not a date or time. | Use eg until=2026-11-06T00:00:00Z, or leave it out (now). |
| invalid_to | 400 | "to" is not a phone number (or a business-scoped user id). | Give the number with its country code, digits only, eg "to": "61412345678". Several numbers: "61412345678,61498765432". |
| invalid_username | 400 | 'transfer_action' must be none or force_transfer. | Send eg {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. |
| invalid_users | 400 | "users" is missing, empty, too long, or has an entry that is not a phone number or a business-scoped user id. | eg {"users": ["61412345678"]} - numbers with their country code, digits only, or business-scoped user ids. |
| invalid_wait | 400 | "wait" is not a whole number of seconds from 0 to 25. | Use ?wait=25 and call again when the answer comes back empty. |
| invalid_webhook_format | 400 | A … webhook gets app2email's event envelope only ("format": "app2email"). | "format" is "app2email" (app2email's event envelope, the default) or "meta" (the events that come from WhatsApp, as Meta's own webhook body). |
| invalid_webhook_headers | 400 | The webhook's headers: …. | Send up to 5 headers as {"headers": {"Authorization": "Basic dXNlcjpwYXNz"}}, values in printable ASCII. Not allowed: Host, User-Agent, Content-*, X-App2email-*, X-Hub-*, Proxy-*, X-Forwarded-* and connection headers. In PATCH a header set to null is removed. |
| invalid_webhook_secret | 400 | "secret" must be text of 1 to … characters. | Leave it out to get a new random secret, or send your receiver's secret, eg "whsec_...". |
| missing_file | 400 | The form has no file (field "file"). | Send the file in the form field "file", eg curl -F 'file=@photo.jpg;type=image/jpeg'. |
| missing_interactive | 400 | "interactive" is required for an interactive message. | Send {"type": "interactive", "interactive": {"type": "button" | "list" | "cta_url", "body": {"text": "..."}, "action": {...}}}. |
| missing_media | 400 | "media.data" (the file as base64) is empty. | {"text": "..."} or {"media": {"data": "<base64>", "filename": "photo.jpg", "mime": "image/jpeg"}, "text": "caption"} or {"template": {"name": "...", "language": "en", "body_params": ["..."]}}, each with "sender": {"name", "email"}. |
| missing_message_id | 400 | "message_id" must be the message_id of a message the contact sent (it starts with 'wamid.'). | Use the message_id of a message.received event or GET /messages?direction=in. |
| missing_numbers | 400 | The request has no "numbers" (or "number"). | Send {"numbers": ["61412345678", "61498765432"]}, or entries with a name and note: {"numbers": [{"number": "61412345678", "name": "John", "note": "unsubscribed in our CRM"}]}. |
| missing_template_language | 400 | Template '…' exists in several languages, so "template.language.code" is required. | Add "language": {"code": "<one of the languages in details>"}. |
| missing_template_name | 400 | "template.name" is required. | Use the exact name of an approved template. GET https://api.app2email.com/v1//templates lists them, with an example request for each. |
| missing_text | 400 | "text.body" is required for a text message. | Send {"type": "text", "text": {"body": "Your message"}}. |
| missing_url | 400 | "link" is missing: the public link of the photo. | Send {"data": [{"event_name": "Purchase", "user_data": {"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"}, "custom_data": {"currency": "AUD", "value": 49.90}}]}. JPG or PNG, up to 5 MB. |
| nothing_to_change | 400 | The request has neither "enabled" nor "config". | Send the fields you want to change; the others stay as they are. |
| range_too_large | 400 | WhatsApp keeps analytics for 1 year: 'since' is further back. | Use a 'since' within the last 365 days. |
| segment_and_recipients | 400 | The request has "segment" together with "to", "recipient" or "recipients". Use one of them. | "segment": "<segment id or name>" sends to the segment's contacts; leave "to" and "recipients" out. |
| segment_empty | 400 | The segment '…' has no contacts, so there is nothing to send. | GET /v1/…/segments/…/contacts shows what it matches. Add contacts (POST /contacts) or change the filter. |
| send_at_in_past | 400 | "send_at" must be at least 1 minute from now (now is …). | Use an ISO 8601 time with its time zone, eg "2026-11-02T09:00:00+11:00" or "2026-11-02T09:00:00Z", between 1 minute and 29 days from now. To send now, leave "send_at" out. |
| send_at_too_far | 400 | "send_at" is more than 29 days from now. | Use an ISO 8601 time with its time zone, eg "2026-11-02T09:00:00+11:00" or "2026-11-02T09:00:00Z", between 1 minute and 29 days from now. |
| shop_invalid | 400 | Something in the request is not valid for the shop: a missing or wrong field of an item, a stock figure, a setting, an order (no name, no time, an address the shop needs). The message names it; error.details.problems lists every problem of an item or of the settings. | Correct what the message names and send the request again. |
| template_insights_confirm_required | 400 | Switching template insights on cannot be undone, so the body must be {"confirm": true}. | Meta then adds link tracking to URL buttons and collects anonymised data from the chats. It applies to every number on this WhatsApp Business Account. Send {"confirm": true} if the account owner agrees. |
| template_language_required | 400 | The template '…' has … languages: say which one with ?language=. | Add ?language=… (one of: …). |
| to_and_recipients | 400 | The request has both "to" and "recipients". Use one of them. | Use "to" when every number gets the same values, or "recipients": [{"to": "61412345678", "components": [...]},...] when each number has its own values. |
| too_many_catchers | 400 | This number has … catchers that have not expired, the most allowed. | Use one of them (GET.../webhooks/catchers), or delete one: DELETE.../webhooks/catchers/…. They expire 1 hour after they were made. |
| too_many_numbers | 400 | … contacts in one request. The most is …. | Split them over several requests, or use POST /contacts/import (up to 5000). |
| too_many_recipients | 400 | The request has more numbers than this WhatsApp number may send to in one request. Nothing was sent. | Split the numbers over several requests. details.max_recipients is the limit; it goes up after messages are delivered. |
| too_many_segments | 400 | This number already has … segments, the most allowed. | Delete one you no longer use. |
| too_many_templates | 400 | That is … templates; WhatsApp reports at most 10 template languages in one request. | Split the list. |
| too_many_webhooks | 400 | This number already has … webhooks, the most allowed. | Delete one you no longer use: DELETE https://api.app2email.com/v1/…/webhooks/<id>. |
| unsupported_message_type | 400 | "type" is not a message type this API sends. | Use "template" to start a conversation. Within 24 hours of the contact's last message other types work too: https://www.app2email.com/docs/api/message-types |
| api_key_expired | 401 | This API key has expired. | Create a new key on https://www.app2email.com/dashboard/apikey. |
| api_key_old_format | 401 | This API key uses the old key format, which app2email no longer accepts (all keys were replaced on 2026-11-15 for security). | Create a new key on https://www.app2email.com/dashboard/apikey and use it instead. New number keys start with 'a2en_' and are 96 characters long. |
| api_key_revoked | 401 | This API key is no longer valid for +…. It was revoked, or a newer Default key has been created. | Use a key that is listed on https://www.app2email.com/dashboard/apikey. Creating a new Default key replaces the previous Default key. |
| invalid_api_key | 401 | This is an account key (a2ea_...), not the API key of a number. | Send to https://api.app2email.com/v1//... with this key, or use the number's own key (a2en_...), made on https://www.app2email.com/dashboard/apikey. |
| invalid_authorization_header | 401 | The Authorization header must be 'Bearer <your API key>'. | Send 'Authorization: Bearer YOUR_API_KEY' with the whole key (it starts with 'a2e_'). |
| missing_api_key | 401 | No API key was sent. | Send 'Authorization: Bearer YOUR_API_KEY'. Keys: https://www.app2email.com/dashboard/apikey |
| account_deactivated | 403 | The login of this account is deactivated. | Contact support@app2email.com. |
| account_not_confirmed | 403 | The person has not confirmed the e-mail address yet. | Ask them to open the link in the e-mail (get_account_status shows what is still needed). |
| api_key_number_mismatch | 403 | +12025550100 is app2email's demo number: only sandbox keys (a2es_...) work on it. This is the API key of a real number. | Use your key with your own number in the URL, or get a sandbox key: POST https://api.app2email.com/v1/account/sandbox (no key, no body) answers a sandbox key for the demo number +12025550100. |
| booking_not_enabled | 403 | Book-and-Pay is not set up for this number yet. | Apply the booking database update (apply_261106_booking_as_admin.sh and apply_261106_booking_2_as_admin.sh), then try again. |
| call_permission_required | 403 | WhatsApp (Meta) error 138006. | The contact has not allowed calls from this number. Send a call permission request (an interactive call_permission_request message) first; GET /calls/permissions/… shows the state. |
| client_not_editable | 403 | This client cannot be changed here: it signed up on app2email itself, or belongs to another site. | The client changes it in their profile, or contact support@app2email.com. |
| display_name_not_approved | 403 | WhatsApp (Meta) error 131037. | The number cannot send until WhatsApp approves its display name. Check the display name in WhatsApp Manager. |
| flow_blocked_by_integrity | 403 | Meta blocks creating or publishing flows on this WhatsApp account (an integrity issue). | Meta blocks creating or publishing flows on this WhatsApp account (an integrity issue). Contact Meta support through WhatsApp Manager. |
| insufficient_scope | 403 | The API key does not have the permission this call needs (the message names it). | Use a key with that permission, or create one on https://www.app2email.com/dashboard/apikey. |
| ip_not_allowed | 403 | The API key '…' cannot be used from this address (…). | Send the request from one of the key's allowed addresses, or change the key's address list on https://www.app2email.com/dashboard/apikey. |
| link_not_usable | 403 | A booking link is expired, revoked, used up, or the online booking page is switched off. | Make a new link with POST /bookings/links, or switch the online booking page on. |
| messaging_limit_restricted | 403 | WhatsApp (Meta) error 131064. | Meta lowered the number's messaging limit because templates had the wrong category. Check the template categories; the limit comes back after Meta's enforcement period. |
| not_in_instant_sandbox | 403 | The instant sandbox (the demo number +12025550100) does not have this call. | It has GET /me, GET /templates, POST /messages, GET /messages, GET /conversations, PUT /conversations/{contact}/owner, GET /events and POST /sandbox/inbound. Everything else needs a connected WhatsApp number (create_account). |
| partner_closed | 403 | The partner account is closed. | Contact support@app2email.com. |
| partner_suspended | 403 | The partner account is suspended: it can read, revoke keys and delete webhooks, nothing else. | Contact support@app2email.com. |
| plan_not_allowed | 403 | This number's plan does not include the API. | Choose a plan that includes the API (Plan in the dashboard menu). |
| recipient_not_opted_in | 403 | The contact has no opt-in record, and this number requires one for marketing templates. | Record their consent first: POST /v1/{number}/optins. Utility templates can still be sent. |
| recipient_opted_out | 403 | +… is on your Do Not Call list (they asked to stop promotions), so marketing templates are not sent to them. | Do not send marketing messages to this person. Utility templates (eg order updates) can still be sent. To remove them from the list, see the Do Not Call list in your dashboard. |
| recipient_stopped_marketing | 403 | WhatsApp (Meta) error 131050. | The person has turned off marketing messages from you in WhatsApp. Do not send them marketing templates. Utility templates still work. |
| sandbox_key | 403 | A sandbox key cannot …: it is for testing sends without sending. | Use a normal key (one without the sandbox flag) from https://www.app2email.com/dashboard/apikey. |
| service_not_live | 403 | The number's service is not live (paused, cancelled or not paid), so nothing can be sent. | Check the service status and the plan in the dashboard; a paused service goes live with 'Go Live' on the Settings page. |
| shop_not_enabled | 403 | The shop is switched off (or has no order page address yet), so it takes no orders and has no customer links. | Switch the shop on in the dashboard: Order-and-Pay, Selling. |
| submit_not_enabled | 403 | Submit-Info is switched off for this number, so nothing is sent to customers. | PUT /submit/settings {"enabled": true}, or switch it on in the dashboard. |
| template_name_reserved | 403 | A template app2email uses itself cannot be deleted here. | Choose another name. |
| tickets_not_enabled | 403 | Ticket sales are not available for this number yet, are not set up for it yet, or are switched off for it. The message says which. | Not available yet: nothing in the request is wrong. Ticket sales are being switched on number by number; ask support@app2email.com when this number is next. Not set up, or switched off: open Tickets on the dashboard once (Integrations) or switch ticket sales on there, or PUT /settings/tickets {"enabled": true}. GET /settings/tickets says which it is. |
| username_not_eligible | 403 | WhatsApp (Meta) error 147002. | This number cannot have a username yet: WhatsApp requires a higher messaging limit. |
| whatsapp_account_locked | 403 | WhatsApp (Meta) error 131031. | Meta has locked your WhatsApp Business account. Check the account status in WhatsApp Manager. |
| whatsapp_account_restricted | 403 | WhatsApp (Meta) error 368. | Meta has temporarily restricted your number for policy reasons. Check WhatsApp Manager for details. |
| whatsapp_payment_issue | 403 | WhatsApp (Meta) error 131042. | Meta could not charge your WhatsApp account. Add or fix the payment method in Meta Business Suite -> WhatsApp Manager -> Payment settings. |
| whatsapp_permission_missing | 403 | WhatsApp did not …: … | Meta has not given app2email the permission this feature needs for your WhatsApp account (the API reference shows what each operation needs from Meta). Retrying does not help; contact support@app2email.com if you need it. |
| approval_not_found | 404 | There is no held send '…' for this number. | GET https://api.app2email.com/v1/…/approvals lists the held sends (they are kept 7 days after they are resolved or expire). |
| automation_not_found | 404 | There is no automation with this id on the number. | GET /submit/automations lists them with their ids. |
| block_not_found | 404 | There is no such time block on this number. | GET /calendar/blocks lists the blocks with their ids. |
| booking_not_found | 404 | There is no such booking on this number. | Reload the appointments page. |
| broadcast_not_found | 404 | There is no broadcast '…' for +…. | Use broadcast.code from the send answer, or GET https://api.app2email.com/v1/…/broadcasts for the latest ones. |
| catcher_not_found | 404 | The catcher '…' has expired (catchers last 1 hour). | Make a new one: POST https://api.app2email.com/v1/…/webhooks/catchers. |
| client_not_found | 404 | There is no client with this id. | GET /v1/partner/clients lists your clients and their ids. |
| connection_not_found | 404 | There is no connection with this key on the number. | GET /submit/connections lists them. PUT /submit/connections/{key} makes one. |
| contact_not_found | 404 | There is no contact '…' for this number. | GET /v1/…/bookings/customers lists the customers. |
| conversation_not_found | 404 | There is no conversation with … yet: they have never written to this number and nothing was sent to them. | A conversation with a business-scoped user id starts when the contact writes to the number. |
| dataset_not_found | 404 | The WhatsApp Business Account has no Conversions API dataset yet. | Create it with POST /v1/…/conversions/dataset. |
| delivery_not_found | 404 | There is no delivery of event '…' for this webhook. | GET.../webhooks/…/deliveries lists them. Deliveries are kept 7 days. |
| flow_json_not_found | 404 | The flow … has no Flow JSON yet. | Upload one with PUT /v1/…/flows/…/json. |
| flow_not_found | 404 | '…' is not a Flow key. | A key is 1 to 40 lower case letters, digits, - or _. |
| form_not_found | 404 | There is no form with this key on the number. | GET /submit/forms lists the forms with their keys. |
| hold_not_found | 404 | There is no such held time on this number. | Use the reference POST /bookings/holds answered. |
| key_not_found | 404 | There is no key with this id. | List the keys (GET /v1/account/keys, or the number's keys) for their ids. |
| link_not_found | 404 | There is no such booking link on this number. | GET /bookings/links lists the links with their codes. |
| list_not_found | 404 | There is no list with this key on the number. | GET /submit/lists lists them. PUT /submit/lists/{key} makes one. |
| media_not_found | 404 | This message has no stored media file. | Only inbound media messages (image, video, audio, document, sticker) received after app2email started keeping copies have a file. media in GET /messages says whether a message had one. |
| member_not_found | 404 | There is no member with this id on the number. | GET /submit/members lists the team with their ids. |
| message_not_found | 404 | No message with id '…' was sent from +12025550100 with this sandbox key. | Use the message_id from the send answer or a message.received event (it starts with 'wamid.'), URL-encoded if it has '/' or '+' in it. |
| note_not_found | 404 | There is no such note on this number (or it was deleted). | GET /bookings/notes?contact=... lists the notes with their ids. |
| number_not_found | 404 | +… is not an active app2email WhatsApp number. | Check the number in the URL. It must be the number registered with app2email (shown on https://www.app2email.com/dashboard/main). |
| optin_not_found | 404 | +… has no opt-in record. | GET.../optins?number=… checks one number. |
| package_not_found | 404 | There is no such package on sale, or the customer has no active package with sessions left for the service. | GET /bookings/packages lists the packages on sale; GET /bookings/packages/purchases?contact= a customer's. |
| payment_not_found | 404 | There is no such payment on this number. | GET /payments lists the payments with their ids. |
| poll_not_found | 404 | There is no such meeting poll on this number. | GET /bookings/polls lists the polls with their ids. |
| qr_code_not_found | 404 | There is no QR code '…' on this number. | GET /v1/…/qr-codes lists them. |
| request_not_found | 404 | No logged request '…' for this number. | Only errors and requests that change something are logged, and rows are kept 30 days. Use the request_id from an API answer. |
| route_not_found | 404 | There is no such webhook family. | Check the method and the path against the reference: https://www.app2email.com/docs/api |
| segment_not_found | 404 | There is no segment '…' for this number. | GET /v1/…/segments lists the segments (use the id or the exact name), POST creates one. |
| shop_not_found | 404 | The item, the order or the shop itself does not exist for this number. | List the items or the orders again and use an id from the answer. A number without a shop: open Order-and-Pay in the dashboard once. |
| submission_not_found | 404 | There is no submission with this id or reference on the number, or it was deleted. | GET /submit/submissions lists them. The path takes the id or the reference. |
| template_language_not_found | 404 | Template '…' has no '…' version. | Use one of the languages in details.available_languages (codes must match exactly, eg 'en' and 'en_US' are different). |
| template_not_found | 404 | There is no template named '…' on this WhatsApp account. Names are lower case and must match exactly. | Use one of the approved templates listed in details.available_templates, or create the template in Meta's WhatsApp Manager and wait for approval. |
| ticket_check_in_not_found | 404 | There is no such check-in on this number. | Use check_in.id from the answer of POST /tickets/check-ins. |
| ticket_code_not_found | 404 | There is no such promo code on this number. | GET /tickets/codes lists the codes with their ids. |
| ticket_date_not_found | 404 | There is no such date on this number. | GET /tickets/events/{id}/dates lists the dates with their ids. |
| ticket_event_not_found | 404 | There is no such event on this number. | Use the id, the slug or the code (EV-XXXXX) from GET /tickets/events. |
| ticket_not_found | 404 | There is no such ticket on this number. | GET /tickets/issued lists the tickets with their ids. |
| ticket_order_not_found | 404 | There is no such order on this number. | Use the id or the reference (TK-XXXXXX) from GET /tickets/orders. |
| ticket_type_not_found | 404 | There is no such ticket type on this number. | GET /tickets/events/{id}/types lists the ticket types with their ids. |
| waitlist_not_found | 404 | There is no such waitlist entry on this number. | GET /bookings/waitlist lists the entries with their references (WL-XXXXXX). |
| webhook_not_found | 404 | There is no webhook '…' for this number. | GET https://api.app2email.com/v1/…/webhooks lists the webhooks and their ids. |
| approval_already_resolved | 409 | This held send was resolved a moment ago. | Nothing to do. Send a new request if the messages are still needed. |
| approval_expired | 409 | This held send expired at … (48 hours after it was held), so it cannot be approved. | Send the request again; it is held again for approval. |
| booking_cancelled | 409 | This appointment is already cancelled. | Nothing to do. Make a new booking if the customer wants another time. |
| booking_slot_taken | 409 | That time is not free… | Read GET.../bookings/availability again and pick one of the slots it gives. |
| broadcast_cancelled | 409 | The broadcast was cancelled before this message was sent. | Send it again in a new request if it is still needed. |
| broadcast_not_cancellable | 409 | The broadcast is finished or already cancelled. | Only API sends that are scheduled or still sending can be cancelled. |
| client_exists | 409 | This e-mail address has an account on your site already. | GET /v1/partner/clients/{client_id} shows it. |
| connection_in_use | 409 | An automation still uses this connection. The message names them. | Change or delete those automations first (GET /submit/automations). |
| delivery_in_progress | 409 | This event is being sent to this webhook right now (its first try or a planned retry). | Wait a few seconds, then look at GET.../deliveries/…: it may be delivered already. Send it again only if it is not. |
| encryption_key_managed | 409 | This number's Flow encryption key is managed by Book-and-Pay (dashboard > Book-and-Pay): WhatsApp keeps one key per number, and the booking Flows need theirs. | Leave the key as it is (GET /v1/…/flows/encryption-key shows it). A Flow of your own with a data endpoint needs a number without Book-and-Pay. |
| flow_name_taken | 409 | The WhatsApp account has a flow with this name already. | A flow with this name exists on the WhatsApp account. Choose another name. |
| flow_not_deletable | 409 | A published flow cannot be deleted. | A published flow cannot be deleted. Deprecate it instead. |
| flow_not_editable | 409 | WhatsApp does not let this flow be changed. | This flow cannot be edited (a deprecated flow, or an older flow without editing). Clone it (POST /flows with clone_flow_id), change the copy and publish that. |
| flow_not_published | 409 | Only a published flow can be deprecated. | Fix what the message says (upload first, fix the validation errors, wait for the encryption key), then publish again. |
| form_exists | 409 | A form with that key already exists on this number, so nothing was written. details names each one. | Give the form another key. To overwrite the existing form on purpose, use POST /submit/setup without "replace": false. |
| form_has_submissions | 409 | The form has submissions, so it cannot be deleted. DELETE /submit/forms/{key} does not answer this: it archives such a form by itself. | Archive the form: PUT /submit/forms/{key} {"archived": true}. |
| form_not_published | 409 | The form is not live on WhatsApp, or could not be made so: it was never published, it is switched off or archived, the number's encryption key is not accepted by WhatsApp yet, or WhatsApp found problems in the generated form. | The message says which. Fix it, then POST /submit/forms/{key}/publish. To get only the web link, POST /submit/forms/{key}/send with link_only true. |
| hold_expired | 409 | The held time is not held any more: it expired, was released, or was already turned into a booking. | Hold the time again with POST /bookings/holds, or read the booking it became. |
| idempotency_request_in_progress | 409 | Another request with this Idempotency-Key was being handled at the same moment. | Wait a few seconds and send the request again with the same key. |
| idempotency_request_interrupted | 409 | The first request with this Idempotency-Key (request_id …, started …) did not finish. Some of its messages may have been sent. | Check what was sent (Activity Log, or GET /v1/…/broadcasts) before sending again. To send again, use a new Idempotency-Key. |
| key_limit_reached | 409 | There are as many keys as allowed (10 per number). | Revoke a key you no longer use first. |
| key_limits_unavailable | 409 | Sandbox keys, daily caps and approval thresholds are not available on this server yet. | Send "sandbox": false without daily_cap and approval_above. |
| number_already_verified | 409 | WhatsApp (Meta) error 136024. | The number is already verified. No code is needed. |
| number_not_live | 409 | The number is not live yet (no plan with the API paid, or not connected), so it has no keys. | Finish the steps get_account_status lists; wait Retry-After seconds. |
| payments_not_connected | 409 | The business has not connected Stripe or PayPal (or the way of paying is not offered). | The account owner connects a provider on the dashboard (Book-and-Pay > Payments) and chooses the methods. |
| plan_already_active | 409 | The number is on this plan already. | Choose another plan, or nothing: it is paid. |
| plan_not_available | 409 | This plan, or this interval, cannot be bought yet. | Choose another plan or interval from list_plans. |
| refund_not_possible | 409 | The payment cannot be refunded: it is not paid, already refunded, or less is left than asked for. | GET /payments/{id} shows its status and what was refunded. |
| segment_exists | 409 | A segment named '…' already exists. | Use another name. |
| shop_changed | 409 | The order (or the total the customer agreed to) changed between your read and this call. | Read the order again, or take the quote in error.details, and repeat the call with what it says now. |
| shop_limit | 409 | The shop has reached a limit, most often the 10,000 items a shop can hold (archived items are not counted). | Archive items that are no longer sold, then try again. |
| shop_not_tracked | 409 | The item (or variant) does not count stock, so its stock cannot be changed. | Send start_tracking true with the figure, or switch stock tracking on for the item. |
| shop_order_problems | 409 | The order cannot be placed as sent: something is sold out, below a minimum, outside the delivery area or not offered. error.details.quote.problems lists each problem with the line it belongs to. | Change the cart or the delivery details and send the order again. |
| shop_sku_taken | 409 | Another item or variant of the shop already has this SKU. | Use another SKU, or change the item that has it. |
| slug_taken | 409 | The public address (slug) is already used by another business. | Choose another address. |
| stage_not_allowed | 409 | The submission cannot move to this stage: the stage needs a note (require_note), or it is kept for other roles (set_by; this limits team members, an API key may choose any stage). | Send note with the change. GET /submit/submissions/{id} shows the form's stages. |
| template_already_exists | 409 | A template with this name and language already exists (or is being deleted). | Use another name or language. A deleted template's name can be used again after about 4 weeks for the same language. |
| template_category_locked | 409 | The category of an approved template cannot be changed (it is …). | Create a new template in the other category, or leave "category" out. |
| template_insights_not_enabled | 409 | WhatsApp did not …: … | Template insights are off for this WhatsApp account. Switch them on once with POST /v1/…/template-insights {"confirm": true} (this cannot be undone). |
| template_not_editable | 409 | The template '…' (…) is …status: WhatsApp edits only APPROVED, REJECTED or PAUSED templates. | Wait until WhatsApp has reviewed it (the template.status_changed event tells you), or delete it and create it again. |
| ticket_event_not_publishable | 409 | The event cannot be published yet. | Fix every point in details.problems, then publish again. |
| ticket_limit_reached | 409 | A limit was reached: 200 events on a number, 400 scheduled dates or 40 active ticket types on an event, or 1,000 promo codes. details.max is the limit. | Archive or delete what is no longer needed, then try again. |
| ticket_not_allowed | 409 | That is not possible in the current state. | The message says why. Read the object again to see its current state. |
| ticket_seat_not_available | 409 | That seat is not available. | Leave seat_keys out to get the best free seats, or pick other seats. details.keys lists the seats concerned. |
| tickets_not_on_sale | 409 | These tickets are not on sale right now, or the date is no longer on sale. | Publish the event and check that the date is scheduled and has not ended and that the ticket type is active. details.reason says cancelled or ended when the date is closed. |
| tickets_sold_out | 409 | Sold out, or fewer are left than were asked for. | details.scope says what is full (type, pool, date or area) and details.left how many are left. |
| too_late | 409 | A customer may no longer cancel or move this appointment online: it is closer than the business's cancel notice. | The customer messages the business, who can change it from the calendar or the API (the business is never limited). |
| username_not_available | 409 | WhatsApp (Meta) error 147001. | This username is taken or not allowed. Try another one (GET /username/suggestions lists names reserved for your business). |
| username_taken | 409 | WhatsApp (Meta) error 147005. | Another number of your business has this username. Move it to this number, or choose another username. |
| waitlist_not_offered | 409 | The waitlist is not offered for that: the service has no waitlist, the day still has free times (or the group time still has room), the day is closed, outside the service's dates or too far ahead, the day's waitlist is full (200), or there is nothing to offer yet. | Switch the waitlist on for the service, pick a full day (or send force: true), or book one of the free times instead. |
| waitlist_not_set_up | 409 | The waitlist is not available on this server yet (it needs an update on our side). | Try again later. |
| webhook_url_in_use | 409 | Another webhook of this number already uses this url. | Change that webhook instead, or delete one of them. |
| approval_body_too_large | 413 | This key holds sends to more than … contacts for approval, but a request of … KB is too big to keep (the most is … MB). | Upload the media once with POST /v1/…/media and send it as {"id": "<media_id>"} instead of base64 data, or split the list. |
| flow_json_too_large | 413 | The request is larger than WhatsApp's 10 MB limit for a Flow JSON. | Make the Flow JSON smaller. |
| media_too_large | 413 | The file is larger than WhatsApp allows for its type. | Send a smaller file (compress the image/video, or reduce the PDF size). |
| request_too_large | 413 | The request body is larger than 1 MB. | WhatsApp allows documents up to 100 MB, images up to 5 MB and videos up to 16 MB. For large files you can also send a "link" instead of base64 "data". |
| test_event_too_large | 413 | The test event is larger than … KB. | Send a shorter event. |
| unsupported_content_type | 415 | The body must be JSON (Content-Type: application/json). | Send the header 'Content-Type: application/json' with a JSON body. Media files go inside the JSON as base64 "data" or as a "link". |
| block_list_full | 422 | WhatsApp (Meta) error 139101. | The block list is full (64,000 users). Unblock some users first. |
| block_users_failed | 422 | WhatsApp did not block any of the users, listed in details.failed. | Only users who wrote to you in the last 24 hours can be blocked. Check each user's error. |
| bsuid_not_supported | 422 | WhatsApp (Meta) error 131062. | WhatsApp cannot send this message to a business-scoped user id: one-tap, zero-tap and copy-code authentication templates need the phone number. Send it to the contact's phone number. |
| caption_too_long | 422 | The text with a file is its caption: … characters, WhatsApp allows up to …. | Shorten the text, or send the file and the text as two messages. |
| flow_cannot_publish | 422 | WhatsApp did not publish the flow: it is not a draft, has validation errors, or failed a publishing check. | Only a draft without validation errors can be published, and the publishing checks must pass (GET /flows/…: validation_errors, health_status). |
| flow_rejected | 422 | WhatsApp did not accept the flow request. | Fix the request as whatsapp_error says and send it again. |
| idempotency_key_reused | 422 | This Idempotency-Key was already used with a different request body. | Use a new key for a different message, or send the first body again. |
| invalid_base64 | 422 | The header … "data" is not valid base64. | Send the file's bytes base64 encoded (standard alphabet, '=' padding), eg in Python: base64.b64encode(open('file','rb').read()).decode(). A 'data:<mime>;base64,' prefix is also accepted. |
| invalid_email | 422 | An e-mail address is not valid. | Give an address like name@example.com, or leave the field out. |
| invalid_media_link | 422 | A media "link" is not a valid http(s) URL. | Use a full public URL, eg: https://example.com/files/photo.jpg - or send the file as base64 in "data". |
| invalid_webhook_url | 422 | The webhook URL is not a public https address that can be reached. | Use a public https:// address that accepts POST requests. |
| marketing_disabled_on_cloud_api | 422 | WhatsApp (Meta) error 131063. | This WhatsApp account blocks marketing templates on the normal send path. Send with "marketing_api": "mm_api", or set messages.marketing_route to auto (PUT /settings/number). |
| marketing_per_user_limit | 422 | WhatsApp (Meta) error 131049. | WhatsApp held this marketing message back: the person has had many marketing messages lately. Do not send it again within 24 hours, because retrying sooner keeps the block longer. |
| media_download_error | 422 | WhatsApp (Meta) error 131052. | WhatsApp could not download the header media. Send it again as base64 "data" or a different link. |
| media_download_failed | 422 | Downloading the header … from the link failed: HTTP …. | Check the link opens in a browser without logging in. Links that need a login, cookies or a signed session do not work - send the file as base64 "data" instead. |
| media_type_not_allowed | 422 | The file type is not allowed for this media. | Convert the file to an allowed type, or set "mime_type" if the type could not be detected. |
| media_upload_error | 422 | WhatsApp (Meta) error 131053. | WhatsApp could not process the header media. Check the file type and size, and that the file opens correctly. |
| message_too_old | 422 | The message arrived on …. WhatsApp only marks messages as read up to … days after they arrived. | Mark a newer message as read: it marks the earlier ones of the chat too. |
| outside_24h_window | 422 | The contact has not written to this number in the last 24 hours (or never), so only a template message can be sent. | Send an approved template message instead ("type": "template"). When the contact answers, normal messages work again for 24 hours. |
| parameter_value_invalid | 422 | WhatsApp (Meta) error 131009. | One of the values is not valid. whatsapp_error.details says which one. |
| reaction_too_old | 422 | The message was received on …. WhatsApp only allows reactions to messages up to … days old. | React to a newer message, or send a text reply. |
| recipient_identity_changed | 422 | WhatsApp (Meta) error 137000. | The contact's identity key changed (eg a new phone) since recipient_identity_key_hash was read. Check it is still the same person, then send with the hash of their latest message.received, or without one. |
| recipient_in_experiment | 422 | WhatsApp (Meta) error 130472. | WhatsApp did not send this marketing message because the person is part of a Meta experiment. Nothing to fix; do not resend it now. |
| recipient_is_sender | 422 | WhatsApp (Meta) error 131021. | The recipient is your own WhatsApp number. Send to a different number. |
| recipient_not_allowed | 422 | WhatsApp (Meta) error 131030. | This WhatsApp number is still in test mode and can only message numbers on its allowed list. Add the recipient in Meta's WhatsApp Manager, or finish the number's setup. |
| recipient_unreachable | 422 | WhatsApp (Meta) error 131026. | WhatsApp could not deliver to this number. Check it is a WhatsApp number written with its country code (digits only, eg 61412345678), and that the person uses an up to date WhatsApp. |
| required_parameter_missing | 422 | WhatsApp (Meta) error 131008. | A required parameter is missing. See example_request for a complete request. |
| sandbox_recipient | 422 | The instant sandbox only writes to its pretend customers, never to a real number. | Use one of the numbers in details.test_contacts. |
| template_archive_failed | 422 | WhatsApp archived no language of '…': …. | Only APPROVED or REJECTED templates can be archived. |
| template_compare_unavailable | 422 | WhatsApp did not compare the templates. | WhatsApp compares only two templates of this account that were each sent at least 1,000 times in the period. Try a longer ?days=. |
| template_disabled | 422 | WhatsApp (Meta) error 132016. | WhatsApp has disabled this template. Create or use another template. |
| template_format_policy | 422 | WhatsApp (Meta) error 132007. | A parameter value breaks WhatsApp's formatting rules. Remove unusual characters or formatting from the parameter values. |
| template_insights_unavailable | 422 | WhatsApp did not …: … | Meta does not offer template insights for this WhatsApp account (not for accounts in the EU or Japan, or not yet). |
| template_limit_reached | 422 | The WhatsApp account has as many templates as Meta allows. | The WhatsApp account has as many templates as Meta allows (250, or 6,000 for a verified business). Delete or archive templates you do not use. |
| template_not_approved | 422 | The template is not APPROVED (pending, rejected, paused or disabled), so WhatsApp will not send it. | Wait for approval, or fix the template in Meta's WhatsApp Manager. Only APPROVED templates can be sent. |
| template_not_marketing | 422 | WhatsApp (Meta) error 131055. | Only marketing templates can go through the Marketing Messages API. Send this template the normal way. |
| template_parameter_count_mismatch | 422 | WhatsApp (Meta) error 132000. | The number of parameters does not match the template. See example_request for the parameters this template needs. |
| template_parameter_format_mismatch | 422 | WhatsApp (Meta) error 132012. | A parameter has the wrong type or format for this template (eg: text where media is expected). See example_request. |
| template_parameter_invalid | 422 | WhatsApp (Meta) error 132018. | A parameter value is not allowed: no new lines, tabs or more than 4 spaces in a row. |
| template_parameters_invalid | 422 | The components do not match the template, listed in details.problems. | Compare with example_request: a complete request for this template with its own sample values. |
| template_paused | 422 | WhatsApp (Meta) error 132015. | WhatsApp has paused this template because of low quality ratings. Use another template, or edit this one in WhatsApp Manager. |
| template_rejected | 422 | WhatsApp did not accept the template. | Fix the template as whatsapp_error says and send it again. |
| template_text_too_long | 422 | WhatsApp (Meta) error 132005. | With your parameter values the message is longer than WhatsApp allows. Use shorter parameter values. |
| template_unarchive_failed | 422 | WhatsApp unarchived no language of '…': …. | Only archived templates can be unarchived, within 28 days of archiving. |
| text_too_long | 422 | "text" is longer than WhatsApp allows. | Shorten the text, or send it as two messages. |
| username_account_not_linked | 422 | WhatsApp (Meta) error 147003, 147004. | The username is used by your Facebook Page or Instagram account: link this phone number to that Page or account in Meta Business Suite first. |
| username_change_limit | 422 | WhatsApp (Meta) error 2655131. | A username can be changed at most 2 times in 14 days. Try again later. |
| voice_needs_ogg_opus | 422 | A voice message ("voice": true) must be an.ogg file with the OPUS codec. This file is of an unknown type. | Convert it, eg: ffmpeg -i in.mp3 -c:a libopus -ac 1 voice.ogg. Or leave "voice" out to send it as a normal audio file. |
| whatsapp_parameter_error | 422 | WhatsApp did not …: … | WhatsApp did not accept a value of the request: whatsapp_error.message and details say which. Fix it and send the request again. |
| daily_cap_reached | 429 | The API key '…' may send … messages per day (UTC); … are used today and this request would send … more. | Wait until midnight UTC, send fewer, or raise the key's daily cap on https://www.app2email.com/dashboard/apikey. |
| media_lookups_paused | 429 | Too many media lookups at WhatsApp failed in the last hour, so they pause for 30 minutes (WhatsApp blocks the number's media lookups otherwise). | Wait, then try again. Use the files app2email stored (message_id of the message) where you can. |
| monthly_cap_reached | 429 | This number's own monthly cap is … messages (outgoing WhatsApp + emails); … are used and this request would send … more. | Wait for the next billing month, send fewer, or raise the cap: PUT /v1/…/settings/number {"caps": {"monthly_messages": <n>}} (0 = no cap) - or on the dashboard's Settings page. |
| monthly_limit_reached | 429 | This number has used all messages in its plan for this billing month. Outgoing WhatsApp messages and outgoing emails both count. | Wait for the next billing month, or move to a plan with more messages. |
| rate_limited | 429 | Too many sandbox keys are being asked for right now. | A sandbox key lasts … days: keep using the one you have. Otherwise wait and try again. |
| register_limit_reached | 429 | WhatsApp (Meta) error 133016. | The number was registered or deregistered too often (10 times in 72 hours). Wait 72 hours before trying again. |
| too_many_invites | 429 | Too many new clients or onboarding links today. | Try again tomorrow (retry_after_seconds), or contact support@app2email.com. |
| too_many_messages_to_recipient | 429 | WhatsApp (Meta) error 131056. | Too many messages to this recipient in a short time. Wait a little before sending to them again. |
| too_many_signups | 429 | Too many sign-ups from this address or for this e-mail address. | Wait retry_after_seconds, then try again. If the person already got an e-mail, use that one. |
| too_many_tests | 429 | This number has sent … test events in the last hour, the most allowed. | Try again in … minutes. |
| whatsapp_rate_limit | 429 | WhatsApp (Meta) error 130429, 80007, 4, 131048. | WhatsApp's rate limit was reached. Slow down and try again in a minute. |
| background_start_failed | 500 | The background send could not be started, so nothing was sent. | Try again in a minute, or send without "background". If it keeps happening, contact support@app2email.com with the request_id. |
| internal_error | 500 | Something went wrong on our side. | Try again. If it keeps happening, contact support@app2email.com with the request_id. |
| schedule_failed | 500 | The send could not be scheduled, so nothing will be sent. | Try again in a minute. If it keeps happening, contact support@app2email.com with the request_id. |
| shop_failed | 500 | The shop could not finish the request. | Try again. If it keeps happening, contact support@app2email.com with the request_id. |
| account_service_error | 502 | The account service gave an answer that is too large. | Try again. If it keeps happening, contact support@app2email.com with the request_id. |
| block_users_error | 502 | WhatsApp had a problem with the block list (Meta error 139103, or no answer). | WhatsApp had a problem with the block list. Try again in a minute. |
| connection_failed | 502 | The OpenAPI document or the MCP tool list of a connection could not be read: the address did not answer, refused the sign-in, or sent something that is not such a document. Answered by POST /submit/connections/{key}/refresh only; a call that fails inside an automation is a failed step of its run. | The message says what failed. Check the address and the secret, then POST /submit/connections/{key}/test. |
| contact_book_error | 502 | Reading the contact book from WhatsApp failed. | Try again in a minute. If it keeps failing, contact support@app2email.com with the request_id. |
| email_not_sent | 502 | The confirmation e-mail could not be sent. | Check the e-mail address and try again in a minute. If it keeps failing, contact support@app2email.com. |
| flow_json_download_failed | 502 | WhatsApp gave no usable download link for the Flow JSON. | Try again in a minute. |
| marketing_status_lookup_failed | 502 | Reading the account's Marketing Messages API status from WhatsApp failed. | Try again in a minute. If it keeps failing, contact support@app2email.com with the request_id. |
| media_delete_failed | 502 | Deleting the media at WhatsApp failed. | Try again in a minute. If it keeps failing, contact support@app2email.com with the request_id. |
| media_lookup_failed | 502 | WhatsApp's answer had no usable download link. | Try again in a minute. If it keeps failing, contact support@app2email.com with the request_id. |
| media_upload_failed | 502 | WhatsApp did not accept the media upload. | Check the file opens and is a supported type. If it keeps failing, try again in a few minutes. |
| payment_link_failed | 502 | The payment link could not be made. | Try again in a minute. If it keeps failing, contact support@app2email.com. |
| payment_provider_error | 502 | The payment provider (Stripe or PayPal) refused the request or could not be reached. | The provider's message is in the error. Try again, or check the account at the provider. |
| profile_photo_failed | 502 | WhatsApp gave no upload handle for the photo. | Try again in a minute. If it keeps failing, contact support@app2email.com with the request_id. |
| shop_payment_failed | 502 | The online payment could not be started at the payment provider, so the order was not kept. | Try again, or place the order with pay later. |
| template_delete_failed | 502 | WhatsApp did not delete the templates. | Try again in a minute. A DISABLED template cannot be deleted. |
| template_lookup_failed | 502 | Could not read your templates from WhatsApp: … | Try again in a minute. If it keeps failing, contact support@app2email.com with the request_id. |
| template_sample_media_failed | 502 | Downloading the header sample from the link failed: HTTP …. | Check the link opens in a browser without logging in. |
| whatsapp_error | 502 | WhatsApp (Meta) refused the request with an error app2email has no own code for. | Read whatsapp_error (Meta's code and text). Try again later; if it keeps failing, contact support@app2email.com with the request_id. |
| whatsapp_flow_failed | 502 | WhatsApp (Meta) refused to create, update or publish the form, or could not be reached. | The message carries Meta's reason. GET /submit/forms/{key} shows flow.validation_errors; fix the definition and publish again. |
| account_service_unavailable | 503 | The account service did not answer in time. | Try again in a minute. If it keeps happening, contact support@app2email.com with the request_id. |
| block_list_busy | 503 | WhatsApp (Meta) error 139102. | The block list was being changed at the same time. Try again in a few seconds. |
| partner_service_unavailable | 503 | The Partner API cannot do this right now. | Try again in a minute (retry_after_seconds). If it keeps failing, contact support@app2email.com. |
| request_log_unavailable | 503 | The request log is not available right now. | Try again later. If it keeps happening, contact support@app2email.com with the request_id. |
| sandbox_unavailable | 503 | The instant sandbox cannot give a key right now. | Try again later. |
| shop_not_ready | 503 | Order-and-Pay is not ready on this server yet. | Try again later. If it keeps happening, contact support@app2email.com with the request_id. |
| submit_not_ready | 503 | Submit-Info is not available on this server yet: a database update is pending. | Try again later. If it keeps happening, contact support@app2email.com with the request_id. |
| whatsapp_connection_problem | 503 | This number has no WhatsApp Business account token, so no template can be made. | Reconnect the WhatsApp account on the Settings page. |
| whatsapp_maintenance | 503 | WhatsApp (Meta) error 131057. | Your WhatsApp account is in maintenance (for example while Meta raises its throughput). Try again in a few minutes. |
| whatsapp_number_not_registered | 503 | WhatsApp (Meta) error 133010. | Your WhatsApp number is not registered with WhatsApp Cloud API at the moment. Contact support@app2email.com. |
| whatsapp_unavailable | 503 | WhatsApp (Meta) error 131016. | WhatsApp is not available right now. Try again in a few minutes. |