Meta Flow Error Codes & Troubleshooting Guide

When creating, publishing, or operating WhatsApp Flows, you may encounter error codes returned by the Meta Graph API, client devices, or endpoint webhooks.

This guide provides an exhaustive reference of all official Meta Flow error codes and their actionable resolutions.

1. Flow Management API Error Codes

These errors occur when calling Meta's Graph API (POST /{waba_id}/flows or POST /{flow_id}/assets):

Error Code	Error Name	Cause	Resolution in SMSPort
`100`	Flow Name Not Unique	A Flow with this exact name already exists under the same WhatsApp Business Account.	Use a distinct name for the Flow in the creation modal.
`100`	Invalid Flow JSON Version	The `version` property in Flow JSON is missing, malformed, or deprecated.	Ensure `"version": "7.3"` is specified at the root of the Flow JSON.
`100`	Invalid `data_api_version`	The endpoint API version is missing or not supported.	Set `"data_api_version": "3.0"` when endpoint mode is enabled.
`139001`	Flow Can't Be Updated	You attempted to update a Flow JSON that is already in `PUBLISHED` state.	Meta forbids editing published Flows. Clone the Flow in SMSPort, edit the new draft, and publish it.
`139002`	Publishing Flow With Validation Errors	The draft Flow contains syntax errors, unresolvable routing links, or broken references.	Review SMSPort's built-in Flow Validation Badge to fix all highlighted red issues before publishing.
`139002`	Missing Flows Signed Public Key	You attempted to publish an endpoint-driven Flow without registering an encryption key.	Navigate to Flow Details > Encryption and click Generate & Register Public Key.
`139002`	Endpoint Not Available	Meta attempted to call your endpoint health check (`ping`), but it timed out or failed.	Verify your server is online and responding with `{"data":{"status":"active"}}` under 10 seconds.
`139003`	Can't Deprecate Unpublished Flow	You attempted to deprecate a Flow that is still in `DRAFT` status.	Only published Flows can be deprecated. Delete draft flows instead.
`139004`	Can't Delete Published Flow	Meta prohibits deleting Flows once they are published.	Use the Deprecate Flow action instead to retire published Flows gracefully.

2. Cloud API Outbound Error Codes

These error codes are returned when attempting to send a Flow message to a user:

Error Code	Status	Cause	Resolution
`132068`	Flow is Blocked	The Flow was automatically blocked by Meta integrity systems due to policy violations or repeated crashes.	Inspect Flow logs and contact Meta Business Support to unblock the Flow.
`132069`	Flow is Throttled	The Flow exceeded failure thresholds (more than 10 consecutive endpoint timeouts within an hour).	Fix endpoint response latency to stay well below the 10-second cutoff.

3. Client & Webhook Runtime Alert Errors

These errors are reported via client device telemetry or webhooks when users interact with a Flow:

Error Code	Trigger Condition	Root Cause & Resolution
`invalid-screen-transition`	Next screen received from endpoint is not in `routing_model`.	Your endpoint returned a `screen` name that was not declared in the Flow JSON's `routing_model` for the active screen. Update the routing model and republish.
`payload-schema-error`	Screen data does not match the schema in Flow JSON.	The JSON structure sent by the endpoint does not match the types declared in `screens[].data`. Verify keys and ensure non-null types.
`timeout_error`	Endpoint processing took longer than 10 seconds.	Optimize backend database queries or offload long-running operations asynchronously.
`public-key-missing`	Client device could not retrieve the business's public key.	Re-register your public key with Meta under the sending phone number ID.
`response-decryption-error`	Client failed to decrypt endpoint response.	Verify you are using the same AES key and the bitwise inverted IV (`IV ^ 0xFF`) to encrypt responses.
`421 (HTTP)`	Payload cannot be decrypted by business.	Re-upload and verify the RSA private key in SMSPort's encryption settings.
`427 (HTTP)`	Flow token is no longer valid.	The customer's session token expired. Send a new message with a fresh flow token.
`432 (HTTP)`	Request signature authentication failed.	Check your Meta App Secret and `X-Hub-Signature-256` validation logic.