API and SDK
Errors
The single error format of the API and the meaning of each code.
Error format
Section titled “Error format”Every API error uses the same JSON body, with a stable code you can handle in your code. This is the real body of a GET /v1/me call without a key:
HTTP/1.1 401 UnauthorizedContent-Type: application/jsonX-Request-Id: req_01a1c036cb127000b175ffba86a20018{ "error": { "code": "missing_api_key", "message": "Missing API key: send Authorization: Bearer <key>", "meta_code": null, "retryable": false, "request_id": "req_01a1c036cb127000b175ffba86a20018", "docs_url": "https://docs.messajo.com/errors#missing_api_key" }}Fields
Section titled “Fields”| Field | Type | What it is |
|---|---|---|
code |
string | Stable Messajo code. Handle the error by it, never by the message. |
message |
string | Short text in English, good for logs. May change between versions. |
meta_code |
number or null |
Meta’s original code when the error came from Meta; null otherwise. |
retryable |
boolean | true when repeating the same call may succeed. |
request_id |
string | Request id, the same as the X-Request-Id header. |
docs_url |
string | Link to the code’s anchor on this page. |
retry_after_ms |
number | Only on limit errors (rate_limited, connection_rate_limited, pair_rate_limited, meta_rate_limited, link_locked): how long to wait, in milliseconds. |
details |
list | { path, message } items. On validation_failed, one per invalid field. On a Meta error, details[0].message carries the detail Meta sent (error_data.details). On outside_service_window, the end of the window (path: "window_ends_at"). |
When to retry
Section titled “When to retry”- Retry only when
retryableistrue. The others need a fix first. - If the response carries
Retry-After(seconds) orretry_after_ms, wait at least that long. - Without
Retry-After, use exponential backoff with jitter (for example 1 s, 2 s, 4 s…) and a cap on attempts. - Message sends are never retried blindly: send the
Idempotency-Keyheader and retry with the same key, so the message is not delivered twice. See Limits.
Messajo codes
Section titled “Messajo codes”Each code has its own anchor (/errors#<code>), the same as in docs_url.
validation_failed
- HTTP status
- 400
- Retryable
- No
- Panel message
- Some fields are invalid. Review them and try again.
- What it means
- The request body, query or parameters did not pass validation.
- What to do
- Read
details: each item carries the fieldpathand the reason. Fix it and send again.
missing_api_key
- HTTP status
- 401
- Retryable
- No
- Panel message
- Send the API key in the Authorization header.
- What it means
- The request arrived without the
Authorization: Bearerheader. - What to do
- Send the key in the
Authorization: Bearer <key>header. The panel cookie does not authenticate the API; see Authentication.
invalid_api_key
- HTTP status
- 401
- Retryable
- No
- Panel message
- Invalid API key.
- What it means
- The key sent does not exist or was revoked.
- What to do
- Check that you copied the whole key, with no spaces. If it was revoked, create a new one in the panel.
api_key_expired
- HTTP status
- 401
- Retryable
- No
- Panel message
- This API key has expired.
- What it means
- The key is past the expiry date set when it was created.
- What to do
- Create a new key in the panel and swap it in your integration before deleting the old one.
api_key_disabled
- HTTP status
- 401
- Retryable
- No
- Panel message
- This API key is disabled.
- What it means
- The key exists, but it was disabled in the panel.
- What to do
- Ask an organization admin to re-enable the key, or use another active one.
unauthenticated
- HTTP status
- 401
- Retryable
- No
- Panel message
- Your session has expired. Sign in again.
- What it means
- The panel route requires a session and there is none, or it expired.
- What to do
- Sign in to the panel again. Integrations should use the
/v1API with a key.
billing_required
- HTTP status
- 402
- Retryable
- No
- Panel message
- Your plan does not allow this action. Review billing.
- What it means
- The organization's plan does not allow this action, or a payment is pending.
- What to do
- Review the plan and billing in the panel. Retrying the call will not help.
org_restricted
- HTTP status
- 403
- Retryable
- No
- Panel message
- This organization is restricted: nothing new can be created until it is settled.
- What it means
- The organization is restricted: it cannot create new items (destinations, campaigns, flows, templates, connection links).
- What to do
- What already exists keeps working. Settle the organization standing in the panel; retrying the call will not help.
org_suspended
- HTTP status
- 402
- Retryable
- No
- Panel message
- This organization is suspended. The panel is read-only until it is settled.
- What it means
- The organization is suspended: the API only answers GET /v1/me and webhooks are held.
- What to do
- Settle the organization standing in the panel. Once reactivated, held webhooks are delivered in order.
forbidden
- HTTP status
- 403
- Retryable
- No
- Panel message
- You do not have permission to do this.
- What it means
- The caller has no access to this resource.
- What to do
- Check that the key or user belongs to the organization that owns the resource.
insufficient_permissions
- HTTP status
- 403
- Retryable
- No
- Panel message
- Your key or role does not have this permission.
- What it means
- The key or role lacks the permission the route requires.
- What to do
- Create a key with the required permission, or ask for a role with more access.
connection_not_allowed
- HTTP status
- 403
- Retryable
- No
- Panel message
- This key has no access to this connection.
- What it means
- The key is restricted to other connections.
- What to do
- Use a key allowed on this connection, or add the connection to the key's permissions.
organization_key_required
- HTTP status
- 403
- Retryable
- No
- Panel message
- This operation requires an organization key.
- What it means
- This operation only accepts an organization key (
mj_), and the key used is a connection key (mjc_). - What to do
- Use an organization key and repeat the call. See Authentication.
two_factor_required
- HTTP status
- 403
- Retryable
- No
- Panel message
- Your role requires two-factor authentication. Turn on 2FA to continue.
- What it means
- Your role requires two-factor authentication and it is off. Only shows up in the panel.
- What to do
- Turn on 2FA under Profile → Security and repeat the action.
two_factor_mandatory
- HTTP status
- 403
- Retryable
- No
- Panel message
- Owners and admins cannot turn off two-factor authentication.
- What it means
- Owners and admins cannot turn off two-factor authentication. Only shows up in the panel.
- What to do
- Keep 2FA on, or have your role changed before turning it off.
no_active_organization
- HTTP status
- 409
- Retryable
- No
- Panel message
- Choose an organization to continue.
- What it means
- The panel session has no organization selected.
- What to do
- Pick or create an organization in the panel and repeat the action.
last_owner
- HTTP status
- 409
- Retryable
- No
- Panel message
- The organization needs at least one owner.
- What it means
- The action would leave the organization with no owner.
- What to do
- Promote another member to owner before leaving or changing your role.
slug_taken
- HTTP status
- 409
- Retryable
- No
- Panel message
- This address is already taken. Choose another one.
- What it means
- An organization with this address already exists.
- What to do
- Choose another address (slug) and send again.
org_limit_reached
- HTTP status
- 409
- Retryable
- No
- Panel message
- You reached the limit of organizations per user.
- What it means
- You reached the limit of organizations per user.
- What to do
- Delete an organization you no longer use or ask the instance admin to raise the limit.
reauth_failed
- HTTP status
- 403
- Retryable
- No
- Panel message
- Wrong password or verification code.
- What it means
- The password or verification code of the reconfirmation is wrong.
- What to do
- Type the password again and, if you have 2FA, the current 6-digit code.
account_delete_blocked
- HTTP status
- 409
- Retryable
- No
- Panel message
- You are the only owner of an organization that has other members. Transfer ownership or delete it first.
- What it means
- You are the only owner of an organization that has other members.
- What to do
- Transfer ownership or delete the organization, then try again.
not_found
- HTTP status
- 404
- Retryable
- No
- Panel message
- We could not find what you were looking for.
- What it means
- The resource does not exist or does not belong to the key's organization.
- What to do
- Check the id and the organization. A resource from another organization also answers 404.
conflict
- HTTP status
- 409
- Retryable
- No
- Panel message
- This record changed or already exists. Refresh the page.
- What it means
- The record changed or already exists with this data.
- What to do
- Fetch the current state of the resource and decide whether to send again.
rate_limited
- HTTP status
- 429
- Retryable
- Yes
- Panel message
- Too many attempts. Wait a moment and try again.
- What it means
- You went over the key or organization limit.
- What to do
- Wait
retry_after_ms(orRetry-After) and try again; see Limits.
internal_error
- HTTP status
- 500
- Retryable
- Yes
- Panel message
- Something went wrong on our side. Try again.
- What it means
- Something failed on our side while handling the request.
- What to do
- Retry with backoff. If it persists, contact support with the
request_id.
missing_signature
- HTTP status
- 401
- Retryable
- No
- Panel message
- The webhook arrived without a signature.
- What it means
- The inbound webhook arrived without the
X-Hub-Signature-256header. - What to do
- Only Meta (or your simulator) should call this URL. Check that the call comes from the right app, signed with its app secret.
invalid_signature
- HTTP status
- 401
- Retryable
- No
- Panel message
- The webhook signature does not match.
- What it means
- The webhook
sha256=signature does not match the configured app secret. - What to do
- Check that
META_APP_SECRETbelongs to the app that signs the webhook and that the body was not changed on the way.
invalid_payload
- HTTP status
- 400
- Retryable
- No
- Panel message
- The webhook content is invalid.
- What it means
- The webhook body is not JSON in the shape Meta sends.
- What to do
- Send the body exactly as Meta produced it, with
Content-Type: application/json.
payload_too_large
- HTTP status
- 413
- Retryable
- No
- Panel message
- The content sent is too large.
- What it means
- The request body is over the maximum accepted size.
- What to do
- Send less content. Large files go through media, not in the body.
channel_not_configured
- HTTP status
- 503
- Retryable
- Yes
- Panel message
- This channel is not configured on the server yet.
- What it means
- The channel has no app secret configured on this server, so the webhook cannot be verified.
- What to do
- Meta retries whatever got a
503.
idempotency_key_reused
- HTTP status
- 422
- Retryable
- No
- Panel message
- This Idempotency-Key was already used for another request.
- What it means
- The
Idempotency-Keywas already used in the last 24 h with another method, path or body. - What to do
- Generate a new key for each different operation. Reuse a key only to resend the same request.
idempotency_in_progress
- HTTP status
- 409
- Retryable
- Yes
- Panel message
- A request with this Idempotency-Key is still in progress.
- What it means
- The first request with this
Idempotency-Keyis still being processed. - What to do
- Wait a few seconds and retry with the same key: you get the stored response.
destination_url_not_allowed
- HTTP status
- 400
- Retryable
- No
- Panel message
- This destination address is not allowed.
- What it means
- The destination URL points to a blocked address (private network,
httpnot allowed, invalid host). - What to do
- Read
details[].messagefor the reason and use a publichttpsURL.
destination_limit_reached
- HTTP status
- 409
- Retryable
- No
- Panel message
- The organization reached its destination limit. Remove one to create another.
- What it means
- The organization already has the maximum number of destinations.
- What to do
- Remove a destination you no longer use before creating another.
destination_paused
- HTTP status
- 409
- Retryable
- No
- Panel message
- This destination is paused. Resume it to continue.
- What it means
- The destination is paused (by you or by the automatic pause after repeated failures).
- What to do
- Fix the endpoint, resume the destination in the panel and redeliver the failed deliveries.
outside_service_window
- HTTP status
- 422
- Retryable
- No
- Panel message
- Outside the 24-hour service window. Send a template.
- What it means
- The contact has not messaged you for more than 24 h (72 h if they came from an ad), so only a template can open the conversation.
- What to do
- Send an approved template. When the contact replies, the window opens again and free-form messages work.
marketing_limit_reached
- HTTP status
- 422
- Retryable
- No
- Panel message
- Meta limited marketing messages to this contact.
- What it means
- Meta held the marketing template to keep the contact's engagement healthy (per-user limit).
- What to do
- Do not resend right away. Wait a few days or send something the contact asks for; an immediate resend will not go through.
pair_rate_limited
- HTTP status
- 429
- Retryable
- Yes
- Panel message
- Too many messages to this contact in a short time. Wait a few seconds.
- What it means
- Meta's pair limit (this number ↔ this contact) was reached.
- What to do
- Wait
retry_after_ms(6 s) before sending to the same contact again. Other contacts are not affected.
meta_rate_limited
- HTTP status
- 429
- Retryable
- Yes
- Panel message
- Meta limited the throughput. Wait and try again.
- What it means
- Meta refused due to the number, account or app throughput limit, without processing the request.
- What to do
- Wait
retry_after_ms(or theRetry-Afterheader) and retry. See Limits.
template_error
- HTTP status
- 422
- Retryable
- No
- Panel message
- Meta rejected the template. See the reason in the details.
- What it means
- The template does not exist in that language, the parameters do not match, the text is too long or it is paused/disabled.
- What to do
- Read
details[].messageandmeta_code. Check name, language and parameters in Templates; a paused or disabled one must be edited.
policy_blocked
- HTTP status
- 403
- Retryable
- No
- Panel message
- Meta blocked this number for a policy violation.
- What it means
- Meta restricted the number or account for violating WhatsApp Business policies. The connection becomes
restricted. - What to do
- See the reason and deadline in the connection health and in WhatsApp Manager; appeal there if you disagree.
connection_needs_reconnect
- HTTP status
- 409
- Retryable
- No
- Panel message
- Access to this connection expired. Reconnect the number.
- What it means
- The Meta token was revoked or expired (password changed, app removed, permission withdrawn). The connection becomes
needs_reconnect. - What to do
- Reconnect from the panel or from the link in the email we sent. Nothing is sent through this connection until then.
meta_payment_required
- HTTP status
- 402
- Retryable
- No
- Panel message
- There is a payment issue on the WhatsApp Business account.
- What it means
- The WhatsApp Business account has no valid payment method, the payment failed or the credit line ran out.
- What to do
- Fix the payment method in Meta Business Manager. Message charges are billed by Meta, not by Messajo.
recipient_not_allowed
- HTTP status
- 422
- Retryable
- No
- Panel message
- This test number only sends to registered recipients.
- What it means
- Meta's test number only sends to up to 5 recipients registered in the app.
- What to do
- Add the recipient in the Meta app dashboard or connect a real number.
media_error
- HTTP status
- 422
- Retryable
- No
- Panel message
- Meta could not process the media.
- What it means
- Meta could not download or accept the media: unsupported type, file too large or unreachable link.
- What to do
- Read
details[].message. Check the accepted types and sizes and, if you sent a link, that it is public and responds quickly.
number_not_registered
- HTTP status
- 409
- Retryable
- No
- Panel message
- This number is not registered on the WhatsApp API yet.
- What it means
- Registering the number on the Cloud API failed or was undone, so Meta does not accept sending from it.
- What to do
- Open the connection in the panel and try registering again. If it persists, reconnect the number.
username_not_eligible
- HTTP status
- 422
- Retryable
- No
- Panel message
- This account cannot have a WhatsApp username yet.
- What it means
- Meta has not enabled usernames for this WhatsApp Business account yet (Meta 147002). Applies to suggestions and to setting the name.
- What to do
- Nothing to fix in Messajo. Try again later; eligibility is decided by Meta and depends on the account.
meta_invalid_parameter
- HTTP status
- 400
- Retryable
- No
- Panel message
- Meta rejected a request parameter.
- What it means
- A field in the body sent to Meta is invalid or does not exist for this message type.
- What to do
- Read
details[].messageandmeta_code, fix the field and send again.
meta_unknown_outcome
- HTTP status
- 502
- Retryable
- No
- Panel message
- Meta did not confirm the send. The message may have gone out; check before resending.
- What it means
- Timeout or temporary Meta failure on a send: there is no way to know whether the message went out. It stays
queueduntil the status arrives by webhook. - What to do
- Do not resend blindly. Confirm via the
message.statusevent or with the contact; repeating with the sameIdempotency-Keyreturns the same 502 without resending. To send again on purpose, use a new key.
meta_error
- HTTP status
- 502
- Retryable
- No
- Panel message
- Meta returned an error.
- What it means
- Meta returned an error that Messajo does not translate into its own code yet.
- What to do
- Read
meta_codeanddetails[].messageand look the code up in Meta's documentation. Keep therequest_idif you open a ticket.
connection_not_active
- HTTP status
- 409
- Retryable
- No
- Panel message
- This connection is not active.
- What it means
- Deprecated: replaced by
connection_pending,connection_disconnected,connection_restricted,connection_disabledandconnection_needs_reconnect; removed in the next major version. It is now only returned when the organization has no active account for the action. - What to do
- Check the connection status in the panel and fix the cause (reconnect, finish setup or wait for the restriction to end).
connection_restricted
- HTTP status
- 409
- Retryable
- No
- Panel message
- The connection is restricted by Meta.
- What it means
- Meta restricted the connection and sending is blocked.
- What to do
- See the reason on the connection in the panel and wait for the restriction to end or resolve it with Meta.
connection_disabled
- HTTP status
- 409
- Retryable
- No
- Panel message
- The connection was disabled by Meta.
- What it means
- Meta disabled the connection.
- What to do
- Check the status on the connection in the panel and open an appeal with Meta if the ban is wrong.
connection_disconnected
- HTTP status
- 409
- Retryable
- No
- Panel message
- The connection is disconnected. Reconnect to use it.
- What it means
- The connection is disconnected and does not send.
- What to do
- Reconnect the connection in the panel.
connection_pending
- HTTP status
- 409
- Retryable
- No
- Panel message
- The connection setup is not finished yet.
- What it means
- The connection setup is not finished.
- What to do
- Finish the connection setup in the panel before sending.
pin_invalid
- HTTP status
- 422
- Retryable
- No
- Panel message
- Incorrect two-step verification PIN.
- What it means
- The two-step verification PIN is incorrect.
- What to do
- Enter the correct PIN for the number. If you forgot it, reset it in the WhatsApp app.
pin_attempts_exhausted
- HTTP status
- 429
- Retryable
- Yes
- Panel message
- Too many attempts for this number. Try again later.
- What it means
- The number reached the registration attempts limit.
- What to do
- Wait the time given in
retry_after_msbefore trying again.
secret_rotation_pending
- HTTP status
- 409
- Retryable
- No
- Panel message
- The previous secret is still valid. Wait until it expires to rotate again.
- What it means
- The destination's previous secret is still valid.
- What to do
- Wait for the previous secret to expire before rotating again.
notification_type_locked
- HTTP status
- 409
- Retryable
- No
- Panel message
- This notification is mandatory and cannot be changed.
- What it means
- This notification type is mandatory and cannot be changed.
- What to do
- Pick another notification type; security and account notifications are always sent.
connection_rate_limited
- HTTP status
- 429
- Retryable
- Yes
- Panel message
- This connection reached its maximum send rate. Wait a moment.
- What it means
- The number is already sending at the maximum speed Meta allows for it (20/s in coexistence, 80/s or more API-only).
- What to do
- Wait
retry_after_msand retry. Nothing is queued: your integration does the retry. See Limits.
account_flagged
- HTTP status
- 403
- Retryable
- No
- Panel message
- This WhatsApp Business account was banned or flagged by Meta.
- What it means
- Meta banned or flagged this WhatsApp Business account for a violation, and it cannot be connected.
- What to do
- Resolve it with Meta in WhatsApp Manager. Once cleared, connect again.
signup_code_invalid
- HTTP status
- 400
- Retryable
- No
- Panel message
- The signup code expired or is invalid. Open the Meta window again.
- What it means
- The
codereturned by the Meta window is valid for 30 s and only once; it expired or was already used. - What to do
- Start the connection again and finish without pausing after the Meta window closes.
signup_scope_mismatch
- HTTP status
- 403
- Retryable
- No
- Panel message
- Some permissions were not granted in the Meta window. Connect again and accept all of them.
- What it means
- The Meta window finished without the permissions to manage and message through the WhatsApp Business account.
- What to do
- Connect again and keep every permission checked in the Meta window.
signup_session_expired
- HTTP status
- 410
- Retryable
- No
- Panel message
- The signup session expired. Start again.
- What it means
- The connection session lasts 30 minutes and ran out, or it was canceled.
- What to do
- Start the connection again from the panel or the connection link.
signup_incomplete
- HTTP status
- 422
- Retryable
- No
- Panel message
- Signup finished without a phone number. Finish it by choosing a number.
- What it means
- The Meta window created or picked the WhatsApp Business account but did not finish with exactly one number.
- What to do
- Connect again and pick (or add) the number in the Meta window all the way to the end.
system_user_assignment_failed
- HTTP status
- 502
- Retryable
- No
- Panel message
- This server could not get access to the WhatsApp account. Ask the instance admin to check the Meta system user.
- What it means
- Meta refused to assign the instance system user (
META_SYSTEM_USER_TOKEN) to the WhatsApp Business account, or its token cannot see the account. - What to do
- The instance admin checks the system user token and id (it must be an admin of the portfolio), then the account connects again. Nothing was saved.
connection_already_exists
- HTTP status
- 409
- Retryable
- No
- Panel message
- This number is already connected.
- What it means
- The number already has a live connection, in this organization or another one.
- What to do
- Use the existing connection. To move it to another organization, disconnect it there first.
waba_owned_by_other_org
- HTTP status
- 409
- Retryable
- No
- Panel message
- This WhatsApp Business Account is already connected to another organization.
- What it means
- The WhatsApp Business Account (WABA) is already connected to another organization.
- What to do
- Disconnect the account in the other organization first, or use the organization that already has it.
invitation_invalid
- HTTP status
- 409
- Retryable
- No
- Panel message
- This invitation is no longer valid. Ask for a new one.
- What it means
- Whoever sent the invitation left the organization or can no longer grant that role.
- What to do
- Ask an organization admin to send a new invitation.
reconnect_mismatch
- HTTP status
- 409
- Retryable
- No
- Panel message
- The reconnection used a different number. Choose the same number as the connection.
- What it means
- During reconnection, the Meta window returned a number or account different from the original connection.
- What to do
- Reconnect choosing the same number. For a new number, create a new connection.
coex_not_on_business_app
- HTTP status
- 422
- Retryable
- No
- Panel message
- Coexistence mode requires a number already on the WhatsApp Business app.
- What it means
- In coexistence mode the number stays on the phone's WhatsApp Business app; this number is not on it.
- What to do
- Install and activate the number on the WhatsApp Business app, or connect in API-only mode.
link_invalid
- HTTP status
- 404
- Retryable
- No
- Panel message
- This connection link does not exist.
- What it means
- The link address is incomplete, mistyped or the link was revoked.
- What to do
- Ask whoever sent it for a new link.
link_expired
- HTTP status
- 410
- Retryable
- No
- Panel message
- This connection link expired.
- What it means
- The link is past its expiry date (30 days at most).
- What to do
- Ask whoever sent it for a new link.
link_used
- HTTP status
- 410
- Retryable
- No
- Panel message
- This connection link was already used.
- What it means
- The link is single-use and already connected a number.
- What to do
- If you need to connect another number, ask for a new link.
link_locked
- HTTP status
- 423
- Retryable
- Yes
- Panel message
- Too many password attempts. This link is locked for a few minutes.
- What it means
- Too many wrong passwords in a row locked the link for a while.
- What to do
- Wait
retry_after_msand try again with the right password.
link_password_required
- HTTP status
- 401
- Retryable
- No
- Panel message
- This link requires a password.
- What it means
- Whoever created the link set a password to open it.
- What to do
- Enter the password that came with the link. Without it, ask whoever sent it.
link_password_invalid
- HTTP status
- 401
- Retryable
- No
- Panel message
- Wrong password.
- What it means
- The password entered does not match the link's password.
- What to do
- Check the password and try again. Several wrong attempts lock the link for a few minutes.
mirror_path_blocked
- HTTP status
- 403
- Retryable
- No
- Panel message
- This Meta API path is blocked by Messajo.
- What it means
- The call through the mirror layer would break the connection (e.g. deregister the number, change the app subscription) and is blocked.
- What to do
- Do it from the panel or Messajo's own route, which keeps the connection consistent.
media_too_large
- HTTP status
- 413
- Retryable
- No
- Panel message
- The file is too large for this media type.
- What it means
- The file exceeds Meta's limit for its type (e.g. 16 MB for audio and video, 5 MB for images, 100 MB for documents).
- What to do
- Compress the file or send it as a document, which accepts more.
media_type_not_supported
- HTTP status
- 415
- Retryable
- No
- Panel message
- This file type is not supported.
- What it means
- The file type (MIME) is not among the ones WhatsApp accepts for that message type.
- What to do
- Convert to an accepted format (e.g. JPEG/PNG, MP4, OGG/Opus, PDF) or send it as a document.
voice_conversion_failed
- HTTP status
- 422
- Retryable
- No
- Panel message
- Could not convert the audio into a voice message.
- What it means
- Converting the audio to OGG/Opus (voice message) failed: corrupted file or a format the converter cannot read.
- What to do
- Send the audio already in OGG/Opus, or as regular audio without
voice.
template_not_found
- HTTP status
- 404
- Retryable
- No
- Panel message
- Template not found.
- What it means
- There is no template with that id, or with that name and language, on this WhatsApp Business account.
- What to do
- Check name and language in Templates, or sync the list with Meta.
coex_not_supported
- HTTP status
- 422
- Retryable
- No
- Panel message
- Not available for coexistence numbers: change it in the WhatsApp Business app.
- What it means
- Coexistence number: Meta does not let the API change the profile, display name or username; that is done in the WhatsApp Business app on the phone.
- What to do
- Change it in the WhatsApp Business app on the connected phone, or use an API-only number.
instagram_account_not_professional
- HTTP status
- 422
- Retryable
- No
- Panel message
- No Instagram professional account was granted in the login. Select the account on the Meta screen (it must be a professional account) and try again.
- What it means
- No professional account was granted in the Instagram login; Meta only opens messaging and content APIs to professional accounts.
- What to do
- On the Meta screen, select the account and make sure it is a professional account managed by the logged-in person, then connect again.
instagram_scope_missing
- HTTP status
- 403
- Retryable
- No
- Panel message
- An Instagram permission for this feature is missing. Reconnect the account and accept all permissions.
- What it means
- The connection was made without the scope this feature needs (comments, publishing or insights).
details[0].messagenames the missing scope. - What to do
- Reconnect the Instagram account and keep every permission checked in the Meta window.
oauth_state_invalid
- HTTP status
- 400
- Retryable
- No
- Panel message
- We could not confirm this connection. Start again from the connect button.
- What it means
- The return from the Meta login carried a
statethat does not match the open connection session (tampered, expired or from another tab). - What to do
- Start the connection again from the panel or the connection link, in the same tab, without reusing old addresses.
messenger_no_pages
- HTTP status
- 422
- Retryable
- No
- Panel message
- No Facebook Page available to connect. Check that you manage the Page and picked it in the Meta window.
- What it means
- No Page chosen in Facebook Login can be connected: it lacks the messaging/manage tasks or is already connected in another organization.
- What to do
- Check that you have full access to the Page (
MESSAGINGorMANAGEtasks), that you checked it in the Meta window and that it is not linked to another organization.
messenger_page_not_granted
- HTTP status
- 403
- Retryable
- No
- Panel message
- This Page was not granted in the Facebook login. Connect again and check the Page.
- What it means
- The chosen Page is not among the ones granted in the Facebook Login window.
- What to do
- Choose a Page from the returned list, or log in again and check the missing Page.
type_not_supported_by_channel
- HTTP status
- 422
- Retryable
- No
- Panel message
- This content type does not exist on this channel.
- What it means
- The
type(or profile field) sent does not exist on the connection's channel, such astemplateon Instagram orcardson WhatsApp. - What to do
- Check the types each channel accepts in the API reference and pick an equivalent one.
tag_not_supported_by_channel
- HTTP status
- 422
- Retryable
- No
- Panel message
- This channel does not accept message tags.
- What it means
- The send carried a
tag(such ashuman_agent) on a connection whose channel has no tags, such as WhatsApp. - What to do
- Remove the
tag. On WhatsApp, outside the 24-hour window, send a template.
human_agent_window_closed
- HTTP status
- 422
- Retryable
- No
- Panel message
- More than 7 days have passed since the contact's last message. Wait for them to write again.
- What it means
- The
human_agenttag only works up to 7 days after the contact's last message, and that period is over. - What to do
- You cannot send until the contact writes again.
detailssays when the window closed.
human_agent_not_approved
- HTTP status
- 403
- Retryable
- No
- Panel message
- The app is not yet approved by Meta to reply as a human agent.
- What it means
- Meta refused the send with
human_agent: the app does not have the Human Agent feature approved in App Review. - What to do
- Request the Human Agent feature in the Meta app's App Review. Until then, reply within the 24-hour window.
meta_permission_denied
- HTTP status
- 403
- Retryable
- No
- Panel message
- Meta denied the permission for this action. Reconnect the account and accept all permissions.
- What it means
- Meta refused the call for lack of permission: a scope was revoked, the role was removed from the Page or the feature is not yet approved for the app.
- What to do
- Check the connection health in the panel. Reconnect accepting every permission; if it persists, check the Meta app's App Review.
private_reply_window_closed
- HTTP status
- 422
- Retryable
- No
- Panel message
- The time to reply to this comment by Direct is over.
- What it means
- A private reply can only be sent up to 7 days after the comment (for a live comment, only during the live).
- What to do
- Reply publicly to the comment, or wait for the contact to message you on Direct.
private_reply_already_sent
- HTTP status
- 409
- Retryable
- No
- Panel message
- This comment already got a Direct reply.
- What it means
- Meta allows a single private reply per comment, and it was already sent.
- What to do
- Continue in the Direct conversation the private reply opened.
comment_not_found
- HTTP status
- 404
- Retryable
- No
- Panel message
- Comment not found.
- What it means
- There is no comment with that id on this connection, or it was deleted.
- What to do
- Check the id in the post's comment list or in the
comment.*events.
comment_not_owned
- HTTP status
- 403
- Retryable
- No
- Panel message
- You can only delete comments on this account's posts.
- What it means
- The comment is on another account's media (for example, a mention), and Meta only lets you delete comments on your own posts.
- What to do
- Hide or reply to the comment, or ask the post owner to delete it.
publication_not_editable
- HTTP status
- 409
- Retryable
- No
- Panel message
- This publication is already in progress and can no longer be changed.
- What it means
- Only scheduled (
scheduled) or queued (queued) publications can be edited or canceled; this one is being created, published or already finished. - What to do
- Follow the publication
status. If it failed, use retry; if it is out, edit or delete the post on Instagram.
publication_media_invalid
- HTTP status
- 422
- Retryable
- No
- Panel message
- The publication media was rejected. Check format, size and duration.
- What it means
- Meta could not process the publication media (container in
ERROR) or it breaks the rules: JPEG image up to 8 MiB, MP4/MOV video up to 300 MiB (story up to 100 MiB). - What to do
- Read
details, which carries Meta'sstatus, fix the file and create the publication again.
media_url_not_public
- HTTP status
- 422
- Retryable
- No
- Panel message
- Meta cannot download the media: the address is not public.
- What it means
- To publish, Meta downloads the media from the URL, and the address sent (or the storage one) is not reachable from the internet.
- What to do
- Use a public HTTPS URL.
media_url_expired
- HTTP status
- 410
- Retryable
- No
- Panel message
- This media link expired and can no longer be downloaded.
- What it means
- The signed attachment URL expired before the download, and Meta does not issue a new one.
- What to do
- Ask the contact to send the file again.
publishing_limit_reached
- HTTP status
- 429
- Retryable
- Yes
- Panel message
- The account reached its publishing limit for the last 24 hours. Try later.
- What it means
- The Instagram account reached its API publishing limit for the last 24 hours (
content_publishing_limit). - What to do
- Wait for
retry_after_msor schedule it for later. Queued publications are postponed automatically for up to 24 h.
container_timeout
- HTTP status
- 504
- Retryable
- No
- Panel message
- Meta took too long to process the media. Try publishing again.
- What it means
- The publication container stayed in processing at Meta for more than 30 minutes.
- What to do
- Retry the publication. If it happens again, reduce the video size or duration.
insights_not_available
- HTTP status
- 422
- Retryable
- No
- Panel message
- There are no insights available for this item.
- What it means
- Meta does not provide insights for this item: a carousel child, an expired story without a snapshot, an old post or an account below the follower minimum.
- What to do
- Query the parent carousel post or a more recent period. Meta data can be up to 48 h late.
welcome_flow_in_use
- HTTP status
- 409
- Retryable
- No
- Panel message
- This welcome flow is used by an ad and cannot be changed.
- What it means
- The welcome flow is linked to an active ad, and Meta does not allow changing or deleting it.
- What to do
- Remove the flow from the ad in Ads Manager, or create a new flow.
signed_request_invalid
- HTTP status
- 400
- Retryable
- No
- Panel message
- The Meta request arrived with an invalid signature.
- What it means
- The deauthorize or data deletion callback arrived without
signed_request, with a signature that does not match the app secret, or with an algorithm other thanHMAC-SHA256. - What to do
- Check that the callback URL in the Meta app points to this server and that
META_APP_SECRETbelongs to the same app.
data_deletion_not_found
- HTTP status
- 404
- Retryable
- No
- Panel message
- We could not find a deletion request with this code.
- What it means
- There is no data deletion request with that confirmation code, or it is over 1 year old and was removed.
- What to do
- Check the code Meta showed when the deletion was requested and copy the whole address.
invalid_cursor
- HTTP status
- 400
- Retryable
- No
- Panel message
- The pagination cursor is invalid. Start again from the first page.
- What it means
- The
cursoryou sent was not produced by this route with these same filters, or it was modified. - What to do
- Send
next_cursorexactly as returned by the previous response, with the same filters. To start over, omitcursor.
retention_out_of_range
- HTTP status
- 422
- Retryable
- No
- Panel message
- Choose a retention period between 7 days and this instance's maximum.
- What it means
- The requested retention period is under 7 days or above the instance maximum (
RETENTION_MAX_DAYS). - What to do
- Pick a value within the range shown in the organization's data settings.
campaign_channel_not_supported
- HTTP status
- 422
- Retryable
- No
- Panel message
- Campaigns are only available on WhatsApp connections.
- What it means
- The chosen connection belongs to a channel without bulk sending. Meta only allows template campaigns on WhatsApp.
- What to do
- Pick a WhatsApp connection in
connection_id.
campaign_template_not_approved
- HTTP status
- 422
- Retryable
- No
- Panel message
- The template must be approved and be a marketing or utility template.
- What it means
- The template is not
APPROVEDat Meta or its category cannot be used in campaigns (onlyMARKETINGandUTILITY). - What to do
- Wait for approval or pick another template. Sync the connection's templates if the status changed at Meta recently.
campaign_template_mapping_invalid
- HTTP status
- 422
- Retryable
- No
- Panel message
- The variable mapping does not cover every template parameter.
- What it means
- A template parameter (header, body or button) has no source in
variable_mapping, or the source does not fit that parameter. - What to do
- Read
details: each item has the parameterpathand the reason. Give it a column, a fixed value or the contact name.
campaign_not_editable
- HTTP status
- 409
- Retryable
- No
- Panel message
- This campaign can no longer be edited in its current state.
- What it means
- Template, mapping and recipients only change in
draft. Name and rate also change inscheduled,pausedandauto_paused. - What to do
- Unschedule the campaign to return it to
draft, or create a new campaign.
campaign_invalid_state
- HTTP status
- 409
- Retryable
- No
- Panel message
- This action is not possible in the campaign's current state.
- What it means
- The requested action (schedule, start, pause, resume, cancel) is not valid from the campaign's current
status. - What to do
- Fetch the campaign, check its
statusand pick an action allowed from it.
campaign_no_recipients
- HTTP status
- 422
- Retryable
- No
- Panel message
- The campaign has no valid recipients.
- What it means
- The campaign has no
pendingrecipient: the list is empty or every row becameinvalid. - What to do
- Import recipients and fix the invalid rows (the import report shows row, column and reason).
campaign_too_many_recipients
- HTTP status
- 422
- Retryable
- No
- Panel message
- The list exceeds the campaign's recipient limit.
- What it means
- The import would exceed the maximum of 100,000 recipients per campaign, or the inline call carried more than 10,000 rows.
- What to do
- Split the list into more than one campaign, or upload a CSV/JSON file instead of an inline list.
campaign_import_in_progress
- HTTP status
- 409
- Retryable
- No
- Panel message
- A recipient import is still in progress.
- What it means
- A recipient file is still being processed, and the campaign cannot be scheduled, started or take another import until it finishes.
- What to do
- Follow the import until
completedorfailedand try again.
campaign_schedule_invalid
- HTTP status
- 422
- Retryable
- No
- Panel message
- Schedule between 1 minute and 90 days from now.
- What it means
scheduled_atis in the past, less than 1 minute from now or more than 90 days ahead.- What to do
- Send an ISO 8601 time with offset within that range. To send right away, start the campaign instead of scheduling it.
spend_cap_reached
- HTTP status
- 409
- Retryable
- No
- Panel message
- The monthly spend cap was reached. Campaigns stay blocked until next month or until you raise the cap.
- What it means
- The organization reached its monthly spend cap with "pause campaigns" on, so campaigns cannot be started or resumed.
- What to do
- Raise the cap in Settings > Costs, turn off "pause campaigns" or wait for next month.
meta_spam_rate_limited
- HTTP status
- 429
- Retryable
- No
- Panel message
- Meta limited the number because of too many reports or blocks.
- What it means
- Meta refused the send (code 131048) because many messages from this number were reported or blocked. Campaigns pause automatically on this error.
- What to do
- Do not resend. Review the list (only people who opted in), the template content and the frequency; wait for the number's quality to recover before resuming.
destination_type_disabled
- HTTP status
- 422
- Retryable
- No
- Panel message
- This destination type is disabled on this server.
- What it means
- The server does not enable this destination type (RabbitMQ, SQS, Kafka or WebSocket). Existing destinations of this type stay paused.
- What to do
- Use a webhook, or ask whoever runs the instance to turn on
DESTINATIONS_<TYPE>_ENABLED.
no_client_connected
- HTTP status
- 503
- Retryable
- Yes
- Panel message
- No WebSocket client is connected to this destination.
- What it means
- The delivery to the WebSocket destination found no connected client (or none acknowledged it). It only shows up as the delivery's last error.
- What to do
- Keep a client connected to
/v1/wswith a valid ticket; the delivery is retried and, after the attempts, goes to the failure list.
ws_ticket_invalid
- HTTP status
- 401
- Retryable
- No
- Panel message
- The WebSocket ticket is invalid, expired or already used.
- What it means
- The ticket sent when opening
/v1/wsdoes not exist, has expired or was already used: each ticket is good for a single connection. - What to do
- Request a new ticket from the API right before connecting and use it once.
ws_session_limit
- HTTP status
- 429
- Retryable
- No
- Panel message
- Too many WebSocket sessions are open for this destination.
- What it means
- The destination already has the maximum number of simultaneous WebSocket sessions.
- What to do
- Close the connections you no longer use (or reuse one) before opening another.
data_request_in_progress
- HTTP status
- 409
- Retryable
- No
- Panel message
- A request of this kind is already in progress.
- What it means
- The organization already has an export or deletion request of this kind queued or running.
- What to do
- Follow the request in the organization's data settings and wait for it to finish.
data_request_limit
- HTTP status
- 429
- Retryable
- Yes
- Panel message
- Export limit for the last 24 hours reached.
- What it means
- The organization already requested 3 exports in the last 24 hours.
- What to do
- Download one of the exports already done or try again after the time given in
retry_after_ms.
data_export_expired
- HTTP status
- 410
- Retryable
- No
- Panel message
- This export expired and the file was deleted.
- What it means
- The export file stays available for 7 days; after that it is deleted.
- What to do
- Request a new export in the organization's data settings.
calling_not_supported_in_coex
- HTTP status
- 422
- Retryable
- No
- Panel message
- Calling is not available for numbers in coexistence with the WhatsApp Business app.
- What it means
- The number is in coexistence with the WhatsApp Business app, and Meta does not offer the Calling API in that mode.
- What to do
- Use a number connected only through the API (without the app) to receive and place calls.
calling_not_enabled
- HTTP status
- 409
- Retryable
- No
- Panel message
- Calling is not enabled for this number.
- What it means
- Calling is turned off in the number's settings.
- What to do
- Enable calling with
PUT /v1/connections/{id}/calling-settings(status: ENABLED) or in the connection's calling settings in the dashboard.
call_not_found
- HTTP status
- 404
- Retryable
- No
- Panel message
- Call not found.
- What it means
- The call does not exist in this organization.
- What to do
- Check the
id(cal_…) and whether the key can access the call's connection.
call_invalid_state
- HTTP status
- 409
- Retryable
- No
- Panel message
- This action is not allowed in the call's current state.
- What it means
- The action is not valid in the call's current state (e.g. accepting a call that already ended).
- What to do
- Read the current status in
detailsorGET /v1/calls/{id}and send only the actions that state allows.
call_sdp_invalid
- HTTP status
- 400
- Retryable
- No
- Panel message
- Invalid SDP.
- What it means
- The SDP is empty, larger than 64 KiB or does not start with
v=0. - What to do
- Send the SDP generated by your WebRTC stack unchanged.
call_sdp_mismatch
- HTTP status
- 409
- Retryable
- No
- Panel message
- The SDP must be the same one sent in pre_accept.
- What it means
- After
pre_accept, Meta requiresacceptto use exactly the same SDP. - What to do
- Keep the SDP from
pre_acceptand send the same text inaccept.
call_permission_required
- HTTP status
- 403
- Retryable
- No
- Panel message
- The contact has not granted permission to be called.
- What it means
- The contact has not granted the business permission to call (Meta 138006).
- What to do
- Ask for permission with an
interactive.call_permission_requestmessage (or a template with that button) and wait for thecall.permission_updatedevent.
call_rate_limited
- HTTP status
- 429
- Retryable
- No
- Panel message
- Meta calling limit reached.
- What it means
- Meta limited calls from this number or to this contact.
- What to do
- Wait before calling again; do not retry in a loop.
call_error
- HTTP status
- 422
- Retryable
- No
- Panel message
- Meta rejected the call request.
- What it means
- Meta rejected the Calling API request with a 138xxx code.
- What to do
- Read
meta_codeanddetails[0].messagefor the reason; fix the request before retrying.
group_not_supported
- HTTP status
- 422
- Retryable
- No
- Panel message
- Groups are not available for this number.
- What it means
- This number has no access to the Groups API (e.g. a number in coexistence).
- What to do
- Use a number connected only through the API and eligible for groups.
group_not_found
- HTTP status
- 404
- Retryable
- No
- Panel message
- Group not found.
- What it means
- The group does not exist in this organization.
- What to do
- Check the
id(grp_…) and whether the key can access the group's connection.
group_not_active
- HTTP status
- 409
- Retryable
- No
- Panel message
- The group is not active.
- What it means
- The group is still being created, was suspended or deleted.
- What to do
- Wait for the
group.createdevent before sending; suspended or deleted groups do not accept messages.
group_participant_limit
- HTTP status
- 422
- Retryable
- No
- Panel message
- Too many participants for a group.
- What it means
- The group would exceed the participant limit (8).
- What to do
- Remove participants before inviting others.
group_message_type_not_supported
- HTTP status
- 422
- Retryable
- No
- Panel message
- This message type cannot be sent to a group.
- What it means
- Meta only accepts text, media and text or media templates in groups.
- What to do
- Send one of those types; buttons, lists and Flows cannot go to a group.
flow_not_found
- HTTP status
- 404
- Retryable
- No
- Panel message
- Flow not found.
- What it means
- The Flow does not exist in this organization.
- What to do
- Check the
id(flw_…) or the Flow's Meta id.
flow_not_editable
- HTTP status
- 409
- Retryable
- No
- Panel message
- The Flow can only be edited while in draft.
- What it means
- The JSON can only change while the Flow is in
DRAFT. - What to do
- Clone the published Flow (
POST /v1/flows/{id}/clone) and edit the copy.
flow_invalid_json
- HTTP status
- 422
- Retryable
- No
- Panel message
- The Flow JSON is invalid.
- What it means
- The Flow JSON failed validation (local or Meta's, code 139001).
- What to do
- Each
detailsitem haspath = flow_json:<line>:<column>and the reason; fix it and upload again.
flow_handler_required
- HTTP status
- 422
- Retryable
- No
- Panel message
- This Flow needs a data exchange handler.
- What it means
- The Flow uses the Messajo endpoint but the customer handler or the endpoint's public HTTPS base is missing.
- What to do
- Set
endpoint.url(public HTTPS) on the Flow; the instance operator needsFLOWS_ENDPOINT_BASE_URLwithhttps:.
flow_key_not_uploaded
- HTTP status
- 409
- Retryable
- No
- Panel message
- The Flow encryption key was not uploaded to an active number yet.
- What it means
- The Flows public key was not uploaded to any active number of the account yet; Meta cannot call the endpoint.
- What to do
- Wait for the key sync or rotate it with
POST /v1/connections/{id}/flow-key/rotateand publish again.
flow_error
- HTTP status
- 422
- Retryable
- No
- Panel message
- Meta rejected the Flow request.
- What it means
- Meta rejected the Flows request with a 139xxx code.
- What to do
- Read
meta_codeanddetails[0].messageand fix it before retrying.
catalog_not_found
- HTTP status
- 404
- Retryable
- No
- Panel message
- Catalog not found.
- What it means
- The catalog does not exist in this organization.
- What to do
- Check the
id(cat_…) and sync the account's catalogs.
catalog_not_linked
- HTTP status
- 409
- Retryable
- No
- Panel message
- The catalog is not linked to this WhatsApp Business account.
- What it means
- The catalog is not linked to the connection's WhatsApp Business account.
- What to do
- Link the catalog (
POST /v1/catalogs/{id}/link) before using it in messages.
product_not_found
- HTTP status
- 404
- Retryable
- No
- Panel message
- Product not found.
- What it means
- The product does not exist in this catalog.
- What to do
- Check the
id(prd_…) orretailer_idand sync the catalog.
commerce_permission_missing
- HTTP status
- 403
- Retryable
- No
- Panel message
- Missing catalog_management permission for this catalog.
- What it means
- The connection token lacks the
catalog_managementpermission for this catalog. - What to do
- Reconnect the number granting catalog access, or use a catalog from the same business.
order_not_found
- HTTP status
- 404
- Retryable
- No
- Panel message
- Order not found.
- What it means
- The order does not exist in this organization.
- What to do
- Check the
id(ord_…).
order_invalid_transition
- HTTP status
- 409
- Retryable
- No
- Panel message
- This status change is not allowed in the order's current state.
- What it means
- The new status does not follow the order flow (e.g.
shippedbefore payment). - What to do
- Read the order's current status and move one step at a time.
order_reference_taken
- HTTP status
- 409
- Retryable
- No
- Panel message
- This reference_id is already used on this connection.
- What it means
- An order with this
reference_idalready exists on this connection. - What to do
- Use a new
reference_idfor each order (up to 35 characters).
order_totals_mismatch
- HTTP status
- 422
- Retryable
- No
- Panel message
- The order totals do not add up.
- What it means
- The total is not subtotal + tax + shipping − discount, or the subtotal is not the sum of the items.
- What to do
- Recompute the amounts in cents (integers) and send again.
payment_not_available
- HTTP status
- 422
- Retryable
- No
- Panel message
- Payment method not available for this order.
- What it means
- The payment method is not available for this order (currency, country or Meta setup).
- What to do
- Use BRL with Pix, payment link or boleto; see the commerce guide.
otp_template_invalid
- HTTP status
- 422
- Retryable
- No
- Panel message
- The authentication template is missing or not approved.
- What it means
- The authentication template does not exist or is not
APPROVED. - What to do
- Create it with
POST /v1/templates/authenticationand wait for approval before sending codes.
body_too_large
- HTTP status
- 413
- Retryable
- No
- Panel message
- The request body is too large for this route.
- What it means
- The request body exceeds this route's limit.
- What to do
- Send a smaller body; large media goes by link or its own upload.
Meta errors in meta_code
Section titled “Meta errors in meta_code”When Meta rejects a call from the simple layer, Messajo returns its own code in code, Meta’s original code in meta_code and Meta’s detail in details[0].message. In the mirror layer (/v1/whatsapp/...) Meta’s response comes back as it was, untranslated: the mirror is Meta itself.
meta_code |
code |
HTTP | What it means | What to do |
|---|---|---|---|---|
| 131047 | outside_service_window |
422 | More than 24 hours have passed since the contact’s last message. Messajo checks this before calling Meta and answers the same code. | Send an approved template to reopen the conversation. |
| 131026 | recipient_unavailable |
422 | The message could not be delivered (number without WhatsApp, old version, terms not accepted). | Do not retry; confirm the number with the contact through another channel. |
| 131049 | marketing_limit_reached |
422 | Meta held the marketing template to protect the user experience. | Do not retry right away; try another day or other content. In a campaign, it pauses on its own from 10%. |
| 131048 | meta_spam_rate_limited |
429 | Meta limited the number on suspicion of spam (many reports or blocks). | Do not retry; wait a few hours and lower the volume. A campaign pauses on its own. |
| 131056 | pair_rate_limited |
429 | Too many messages from the same number to the same contact in a short time. | Wait for retry_after_ms (6 s) and space out the sends; see Pair rate limit. |
| 130429 · 80007 · 4 | meta_rate_limited |
429 | The number or the app went over Meta’s throughput. | Retry after Retry-After; see Sending per number. |
| 132000 | template_error |
422 | The number of variables sent does not match the template. | Send exactly the parameters the template defines. |
| 132001 | template_error |
422 | The template does not exist in the requested language or is not approved yet. | Check the template’s name, language and status. |
| 132005 | template_error |
422 | The template text with the variables exceeded the maximum length. | Shorten the variable values. |
| 132007 | template_error |
422 | The variable content violates Meta’s policy. | Review the text sent in the variables. |
| 132012 | template_error |
422 | A parameter’s format does not match the template (e.g. image instead of text). | Send each parameter with the type the template defines. |
| 132015 | template_error |
422 | The template was paused for low quality. Messajo marks the template as PAUSED. |
Edit the template or use another one until quality recovers. |
| 132016 | template_error |
422 | The template was disabled for repeated low quality. Messajo marks the template as DISABLED. |
Create a new template. |
| 132068 · 132069 | template_error |
422 | The template’s Flow is blocked or throttled. | Fix the Flow in WhatsApp Manager. |
| 368 · 131031 | policy_blocked |
403 | The account was blocked for violating Meta’s policy. The connection becomes Restricted. | Check the reason in WhatsApp Manager and fix it before sending again. |
| 190 · 102 | connection_needs_reconnect |
409 | The connection’s access token is invalid or expired. | The connection becomes needs_reconnect and owners and admins get an email with a reconnect link. Reconnect. |
| 131042 | meta_payment_required |
402 | A problem with the account’s payment method at Meta. | Fix the payment in Business Manager. |
| 131030 | recipient_not_allowed |
422 | Test number: the recipient is not on the allowed list. | Add the recipient in the Meta app dashboard. |
| 131051 · 131052 · 131053 | media_error |
422 | Unsupported message type, or Meta could not download or upload the media. | Check the format and size; use media_id instead of link. |
| 138006 | call_permission_required |
403 | The contact has not given the business permission to call. | Ask for permission (see Calls) and wait for call.permission_updated. |
| 138xxx (call limits) | call_rate_limited |
429 | Meta’s call or permission request limit was exceeded. | Wait; do not retry right away. |
| 138xxx (others) | call_error |
422 | Meta rejected the call action. | See details[0].message. |
| 139001 | flow_invalid_json |
422 | Meta rejected the Flow JSON. | Fix the spot cited in details (flow_json:<line>:<column>). |
| 139xxx (others) | flow_error |
422 | Meta rejected the Flow operation. | See details[0].message. |
| 200 · 10 on a catalog | commerce_permission_missing |
403 | The app lacks the catalog_management permission. |
Reconnect accepting the catalog permission. |
| 133005 | pin_invalid |
422 | The number already has a two-step verification PIN and the PIN given does not match. The connection stays pending with reason pin_required. |
Enter the 6-digit PIN on the connection page (or the connection link). If you don’t remember it, reset the PIN in WhatsApp Manager. |
| 133016 · 133008 · 133009 | pin_attempts_exhausted |
429 | Limit of 10 registrations per number in 72 h, or Meta asked to wait. Messajo counts the calls and never sends the 11th. | Wait for the response’s retry_after_ms. |
| 133010 | number_not_registered |
409 | The number is not registered on the Cloud API. | On the connection page, use Retry registration. |
| 147002 | username_not_eligible |
422 | The account is not yet eligible for a WhatsApp username on Meta. | Try again later; Meta decides eligibility. |
| 100 | meta_invalid_parameter |
400 | Invalid parameter in the call. | Fix the field named in details[0].message. |
| 131000 · 131016 · 133004 · 5xx | meta_unavailable |
503 | Meta is down or overloaded, on a read. | Retry with backoff. |
| 131000 · 131016 · 133004 · 5xx | meta_unknown_outcome |
502 | The same failure, but on a send: the message may have gone out. | Do not resend blindly; see below. |
| other | meta_error |
502 | A Meta code Messajo does not translate. | Check meta_code and details[0].message. |
Instagram and Messenger
Section titled “Instagram and Messenger”Instagram and Messenger share the same table, with Meta’s code and subcode (meta_code / subcode). The mirror (/v1/instagram/..., /v1/messenger/...) returns Meta’s answer untranslated.
meta_code |
code |
HTTP | What it means | What to do |
|---|---|---|---|---|
| 10 / 2018278 · 10 / 2534022 | outside_service_window |
422 | Outside the 24 h window (or the 7-day one with the tag). | Wait for the contact to write; a reply from a person can use tag: "human_agent". |
| 551 · 100 / 2018001 · 100 / 2534014 | recipient_unavailable |
422 | The contact is not available (blocked the account, deleted the profile or never chatted). | Do not retry. |
10 / 2018065 · 200 with tag: human_agent |
human_agent_not_approved |
403 | The HUMAN_AGENT tag was used without the Human Agent feature approved. |
Request the feature in App Review or reply within 24 h. |
| 10 / 2534023 | private_reply_already_sent |
409 | The comment already got a private reply. | Continue the conversation in Direct. |
| 4 · 17 · 32 · 613 · 80006 | meta_rate_limited |
429 | The account or the app went over Meta’s throughput. | Retry after Retry-After. |
| 190 · 102 | connection_needs_reconnect |
409 | The account or Page token is invalid. | The connection moves to needs_reconnect; reconnect. |
| 10 · 200 without a mapped subcode (Messenger) | connection_needs_reconnect |
409 | The person who connected lost their role on the Page. The connection moves to needs_reconnect with reason page_role_lost. |
Reconnect with someone who manages the Page. |
| 200 / 2018028 · 10 · 3 | meta_permission_denied |
403 | A permission for this action is missing. | Reconnect accepting all permissions. |
| 100 / 2018047 | media_error |
422 | Attachment rejected (type, size or URL). | Check the format and size; use media_id. |
| 368 · 10 / 2018320 | policy_blocked |
403 | Meta blocked it due to policy. The connection moves to Restricted. | Check the reason at Meta before sending again. |
| 9 / 2207042 | publishing_limit_reached |
429 | The quota of 100 publications in 24 h is full. | Messajo tries again every hour for up to 24 h. |
| 2207xxx | publication_media_invalid |
422 | Meta did not accept or could not download the publication media. | Check the format, the size and whether the URL is public. |
| 1 · 2 · 5xx | meta_unavailable |
503 | Meta is down, on a read. | Retry with backoff. |
| 1 · 2 · 5xx | meta_unknown_outcome |
502 | Same failure, on a send: the message may have gone out. | Do not resend blindly; see below. |
| other | meta_error |
502 | Meta code without a Messajo translation. | See meta_code and details[0].message. |
Send with no certain answer
Section titled “Send with no certain answer”When Meta fails in the middle of a send (timeout, 5xx), there is no way to know whether the message went out. Messajo does not retry: it records the message with the meta_unknown_outcome error and answers 502 with retryable: false. Check with the contact or on the phone before sending again. Repeating with the same Idempotency-Key returns the same response, without resending; to send again on purpose, use a new key.
Contact support
Section titled “Contact support”Send the error’s request_id (or the X-Request-Id header), the approximate time and the code. With the request_id support finds the exact request in the logs.