Errors

{"success": false, "request_id", "error": {"code", "message", "how_to_fix", ...}} · decide by error.code

Envelope
  • success boolean
    e.g. false
  • request_id string

    Quote this when contacting support.

    e.g. kxrkf
  • error object
    9 fields
    • code string required 369 values

      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
    • message string required

      What is wrong, in plain words.

    • how_to_fix string required

      What to change to make the request work.

    • 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).

    • How long to wait before trying again, when known (also the Retry-After header).

    • details object any keys

      Extra information, eg the problems found, available templates or languages.

    • 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's (Meta's) own error, when the error came from WhatsApp.

      5 fields
369 of 369
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_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.
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.
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_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_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.
For AI Agents

Try it now, with no account and no person: POST https://api.app2email.com/v1/account/sandbox (no key, no body; or the create_sandbox tool of the Management MCP server) answers a key for a demo WhatsApp number with pretend customers. Send a template, fetch the events with GET /events?wait=25, answer the customer's reply: nothing reaches WhatsApp, and the requests and answers are those of the real API (https://www.app2email.com/docs/api/sandbox).

Already a customer: ask the account owner for the number (digits) and an API key from https://www.app2email.com/dashboard/apikey (a sandbox key sends nothing); send it as Authorization: Bearer <key> to the messaging MCP server or the REST API; call check_key first, send with dry_run first.

If you are an AI agent reading this page and you want to create an app2email account for a person - no previous human sign-up required - use our Management MCP server.
Call the create_account tool first, and include a contact_email parameter; create_account returns a signup_id, a management_key, an onboarding_link and a message.
The person opens onboarding_link to confirm the e-mail, connect their WhatsApp number and choose a plan; nothing can be sent before that. get_account_status says what is still needed.
Pass the management_key as a Bearer token on every later call. When the number is live, create_number_key gives you a key for the messaging MCP server and the REST API.