WhatsApp Business Platform > WhatsApp Flows

Error Codes

Flow Management API Error Codes

When managing (creating, updating, deleting, or publishing) your Flows, you may run into the occasional error. The following table outlines the different error codes you might see, and what you can do to fix the problem.

Don't see your error code listed below? Check out this list of Cloud API error codes.

Error Code	Description	Possible Solutions
100	Flow name is not unique	You may be trying to create a Flow with a name already used by another Flow on the same WhatsApp Business Account. Flow name should be unique within one WhatsApp Business Account. Confirm that you're creating the Flow on the correct account or use a different name for your Flow. See Creating a Flow for more information.
	Invalid Flow JSON version	The Flow JSON version you specified in your API call isn't valid. Verify there isn't a mistake with version sent (e.g., a typo or leaving it blank). If the version looks correct, it may be expired and you'll need to upgrade to a later version. For the latest active versions see the Changelog. For more details on how versioning works for WhatsApp Flows, see the Versioning reference.
	Invalid Flow JSON `data_api_version`	The Data API version you specified in your API call isn't valid. Verify there isn't a mistake with version sent (e.g., a typo or leaving it blank). If the version looks correct, it may be expired and you'll need to upgrade to a later version. For the latest active versions see the Changelog. For more details on how versioning works for WhatsApp Flows, see the Versioning reference.
	Flow with specified ID does not exist	The Flow ID you provided was not found in your account. Confirm that the ID provided is correct and verify that you have access it with the credentials provided.
	Only one clone source can be set	You provided values for both `clone_flow_id` and `clone_template`. When cloning a Flow, you can only provide one of these fields. Unset one of them and try your request again.
	Specify Endpoint Uri in Flow JSON	You provided `endpoint_uri` and `clone_flow_id` which corresponds to a Flow with Flow JSON version below 3.0. For Flow JSON versions below 3.0 `endpoint_uri` should be specified as `data_channel_uri` property in the Flow JSON. Do not specify `endpoint_uri` param when cloning a Flow with Flow JSON version below 3.0. See API reference for details.
	Invalid Endpoint URI	Provide a valid URL.
139000	Blocked By Integrity	Unfortunately we've identified an issue with integrity in your account and have prevented you from creating or publishing your Flow. To get this issue resolved for your account, get in touch with us via the Support.
139001	Flow can't be updated	You attempted to update a Flow that has already been published. Once published, Flows can no longer be updated (see Flows Status Lifecycle). To update a published Flow, you'll have to clone the Flow (see Creating a Flow) and republish the new Flow. Once published, you can start sending the newly modified Flow instead of the existing one.
	Error while processing Flow JSON	Due to an internal error, the Flow JSON was saved but internal processing failed (which may prevent the Flow from serving properly). First, retry the exact same request as the issue may be transient. If retrying results in the same error again, contact us via the support to help get the error resolved.
	Specify Endpoint Uri in Flow JSON	You provided `endpoint_uri` param for a Flow with Flow JSON version below 3.0. For Flow JSON versions below 3.0 `endpoint_uri` should be specified as `data_channel_uri` property in the Flow JSON. Do not specify `endpoint_uri` param when updating a Flow with Flow JSON version below 3.0. See API reference for details.
139002	Publishing Flow in invalid state	You tried to publish a Flow that isn't a draft. Once a Flow leaves the draft state, they cannot be republished (see Flows Status Lifecycle). If you need to modify a Flow that is no longer a draft, you'll have to clone the Flow (see Creating a Flow) and republish the new Flow. Once published, you can start sending the newly modified Flow instead of the existing one.
	Publishing Flow with validation errorrs	You tried to publish a draft Flow that has validation errors. Flows with validation errors can be saved as a draft, but not published. Try viewing the Flow in the Flow Builder UI which will highlight and explain any errors (see Create Your First Flow for a guide to getting started with the Flows Builder UI. You can also view a list of validation errors for your Flow via the API (see Retrieving Flow Details). Once the errors are resolved, try publishing your Flow again.
	Publishing Flow without `data_channel_uri`	You need to set the "data_channel_uri" property before you can send or publish a flow.
	Publishing without specifying `endpoint_uri` is forbidden	Please set `endpoint_uri` property for a Flow before publishing. Starting from Flow JSON version 3.0 `endpoint_uri` should be specified via API. See API reference for details.
	Versions in Flow JSON file are not available for publishing	The flow is using an unsupported version. You can check the list of currently available versions in the changelog.
	No Phone Number connected to WhatsApp Business Account	You need to add a phone number to your WhatsApp Business Account before you can send or publish a flow.
	Missing Flows Signed Public Key	You need to upload and sign a public key to a phone number before you can send or publish a flow.
	No Application Connected to the Flow	You need to connect a Meta app to the flow before you can publish it.
	Endpoint Not Available	You need to verify that the endpoint is available and that you’ve implemented a health check before publishing.
	WhatsApp Business Account is not subscribed to Flows Webhooks	You need to verify that your WhatsApp Business account is subscribed to Flows webhooks.
139003	Can't deprecate unpublished flow	You attempted to deprecate a Flow that hasn't yet been published. Deprecating a Flow is only permitted after it's been published (see Deprecating a Flow). For Flows that are still drafts, you should delete any Flows you no longer need (see Deleting a Flow).
	Flow is already deprecated	You tried to deprecate a Flow that is already marked as deprecated. You may ignore this error as your target state (the Flow being deprecated) has already been achieved.
139004	Can't delete published Flow	After a Flow has been published, it cannot be deleted. Please deprecate instead.
139006	Metrics threshold is not reached	Not enough data to provide flow metrics

Business Endpoint Error Codes

If the Flow is using a business-provided endpoint, that endpoint may return specific HTTP response codes in case of certain types of errors to trigger appropriate client-side behavior.

HTTP Response Code	Server-side situation	Client-side behavior and details
421	The payload cannot be decrypted due to a private key being updated by your business	The WhatsApp client will re-fetch a public key and re-send the request. If the request fails, an error modal appears with an acknowledge button which directs the user back to your chat thread. See Implementing Endpoints for Flows for more details.
432	The request signature authentication fails	A generic error will be shown on the client.
427	The Flow token is no longer valid	The layout will be closed and the CTA button will be disabled for the user. You can send a new message to the user generating a new Flow token. This action may be used to prevent users from initiating the same Flow again. You are able to set an error message to display to the user. For example: HTTP/2 427 content-type: application/json content-length: 51 date: Wed, 06 Jul 2022 14:03:03 GMT {“error_msg”: “The order has already been placed”} See Implementing Endpoints for Flows for more details.

HTTP Response Code

Server-side situation

Client-side behavior and details

421

The payload cannot be decrypted due to a private key being updated by your business

The WhatsApp client will re-fetch a public key and re-send the request. If the request fails, an error modal appears with an acknowledge button which directs the user back to your chat thread.

See Implementing Endpoints for Flows for more details.

432

The request signature authentication fails

A generic error will be shown on the client.

427

The Flow token is no longer valid

The layout will be closed and the CTA button will be disabled for the user. You can send a new message to the user generating a new Flow token. This action may be used to prevent users from initiating the same Flow again.

You are able to set an error message to display to the user. For example:

HTTP/2 427
content-type: application/json
content-length: 51
date: Wed, 06 Jul 2022 14:03:03 GMT

{“error_msg”: “The order has already been placed”}

See Implementing Endpoints for Flows for more details.

Error Types Reported via WebHook Alerts or Propagated Back to Endpoint

These error codes might be sent through business endpoint from client devices or be included in webhook alert payload.

Code	Description	Possible Solutions
`timeout_error`	Endpoint request has timed out. It took more than 10 seconds to process the endpoint request.	Improve the endpoint performance so it can process requests in less than 10 seconds.
`missing_capability`	The app linked to Flow does not have required endpoint capability
`cannot_be_served`	The Flow message cannot be sent and opened by recipients.	Flow is not in `DRAFT` or `PUBLISHED` state. Other common problems: WABA is blocked by Integrity. Check the Business account page for any quality issues. The `version` or `data_api_version` properties are missing in Flow JSON. Add these properties to the Flow JSON file
`no_http_response_error`	Endpoint request connection closed without receiving valid http response.	Ensure that the endpoint always returns a valid response in the correct format.
`unexpected_http_status_code`	The endpoint response had unexpected status code (eg. `500`)	Ensure that the endpoint response always has expected status code.
`public-key-missing`	The client was not able to retrieve the business's public key from WA servers.	Make sure that the correct flow public key is uploaded for the phone number from which you are sending flows. If a problem persists contact support.
`public-key-signiture-verification`	The client was not able to verify the signature of the business's public key.	Make sure that the correct flow public key with signature is uploaded for the phone number from which you are sending flows. If you re-installed on-prem client recently please make sure you re-upload public key with updated signature. If a problem persists contact support.
`response-decryption-error`	The client failed to decrypt the payload sent by the business.	Verify that the same key is uploaded for the phone number and is also being used to encrypt endpoint payloads. If a problem persists contact support.
`invalid-screen-transition`	The client received the next screen which is not matching the routing model expressed in flow JSON layout.	Next screen navigation needs to match what’s expressed in the routing model of the flow layout. If the routing model needs to be updated for a published flow, the flow needs to be cloned, edited and published again.
`payload-schema-error`	The client received the screen data which are not conforming to screen data schema defined in flow JSON layout.	Make sure the screen data sent for each screen complies with the schema defined in the flow JSON layout.
`business-decryption-error`	The client received the 421 error code from the business even after refreshing the public key.	Re-upload the Flow's public key and try again.