Error Messages

List of common API errors you might encounter.

Common API errors

Type: The Path is Blocked

Error code: 403

Description: Response returned if path is blocked.

Payload:

{
    "meta": {
        "httpCode": 403,
        "developerMessage": "This URL *** is blocked. More info: https://docs.360dialog.com/whatsapp-api/whatsapp-api",
        "success": false
    }
}

What to do: Get in touch with our Support team and let us know what you are trying to achieve / describe your use case. If possible, we will enable the API for you.

Type: Invalid API Key

Error code: 401

Description: Invalid API key

Payload:

{
    "meta": {
        "httpCode": 404,
        "developerMessage": "Invalid api_key or token expired",
        "success": false
    }
}

What to do: Generate another API key

Type: WhatsApp Business API has been disabled

Error code: 400

Description: Response returned if WhatsApp Business API has been disabled.

Payload:

{
    "meta": {
        "httpCode": 400,
        "developerMessage": "Your WhatsApp for Business API has been disabled. If you believe this is a mistake, please contact our support team.",
        "success": false
    }
}

What to do: If you expected the account to be live, please contact our support team.

Type: Usage Limit

Error code: 400

Description: Endpoint calls limits has been exceeded.

Payload:

{
    "meta": {
        "httpCode": 400,
        "developerMessage": "You have exceeded the limit of 1 request every * seconds. Try again later.",
        "success": false
    }
}

What to do: Means you are trying to make too many calls in too little time. See Capacity Rate Limits for more information.

Type: Internal Server Error

Error code: 500

Description: Regular accounts can restart every 24h at a time that cannot be scheduled. These restarts take a maximum of 10 minutes.

Possible payloads:

{
    "meta": {
        "httpCode": 500,
        "developerMessage": "Internal server error",
        "success": false
    }
}

{
    "meta": {
        "success": false,
        "http_code": 555,
        "developer_message": "Internal server error"
    }
}

<html>
<head><title>503 Service Temporarily Unavailable</title></head>
<body>
<center><h1>503 Service Temporarily Unavailable</h1></center>
<hr><center>nginx</center>
</body>
</html>

What to do: If you are receiving this error for more than 10 minutes, please contact our support team. If you want to avoid these restarts, please consider upgrading the account to the Premium Package.

Type: WhatsApp for Business API not available

Error code: 502

Description: Error returned if integration with WhatsApp Business does not exist in system or integration is not in running state (WhatsApp Business stack is not running).

Payload:

{
    "meta": {
        "httpCode": 502,
        "developerMessage": "WhatsApp for Business API not available.",
        "success": false
    }
}

What to do: Check this account's status to ensure it is running.

Errors during Number Registration

These always have the code 403 and are described as Trigger registration error.

Type: Timeout

Error code: 1005

Description: This means that Meta has put the registration on "timeout".

Payload:

{
    "data": {
        "code": 1005,
        "details": "Please wait 1 hour(s) 38 minute(s) before trying again",
        "title": "Access denied"
    },
    "meta": {
        "developer_message": "Trigger registration error",
        "http_code": 403,
        "success": false
    }
}

What to do: Wait until the timeout phase has lapsed and try again.

Type: Unknown error: biz_link_error

Error code: 1005

Description: This means the previous WhatsApp installation was uninstalled from the device but not fully deleted.

Payload:

{
    "data": {
        "code": 1005,
        "details": "Unknown error: biz_link_info_invalid_payload",
        "title": "Access denied"
    },
    "meta": {
        "developer_message": "Trigger registration error",
        "http_code": 403,
        "success": false
    }
}

What to do: In the device running the WhatsApp App the number was previously registered in, reinstall WhatsApp and then fully delete it.

Type: Number linked to active non-enterprise account

Error code: 1005

Description: This means the previous WhatsApp installation was not deleted.

Payload:

{
    "data": {
        "code": 1005,
        "details": "This number has not been approved for an enterprise. Please contact support for more info.",
        "title": "Access denied"
    },
    "meta": {
        "developer_message": "Trigger registration error",
        "http_code": 403,
        "success": false
    }
}

What to do: In the device running the WhatsApp App the number is registered fully delete the account and app.

Type: Error verifying the number

Error code: 1005

Description: This means that the registration has been locked.

Payload:

{
    "data": {

Type: Message Undeliverable

Error code: 131026

Description: The following scenarios can cause a message to appear as sent but not delivered. For many of these reasons, Meta does not disclose the underlying cause of the error, due to privacy and policy reasons.

The recipient phone number is not a WhatsApp phone number.
The customer has blocked the business.
The customer is in a restricted or sanctioned country.
Recipient has not accepted Meta's new Terms of Service and Privacy Policy.
Recipient using an old WhatsApp version; must use the following WhatsApp version or greater:
- Android: 2.21.15.15
- SMBA: 2.21.15.15
- iOS: 2.21.170.4
- SMBI: 2.21.170.4
- KaiOS: 2.2130.10
- Web: 2.2132.6

What to do: Using a non-WhatsApp communication method, ask the WhatsApp user to:

Confirm that they can actually send a message to your WhatsApp business phone number
Confirm that your WhatsApp business phone number is not in their list of blocked numbers (Settings > Privacy > Blocked or Blocked contacts)
Confirm that they have accepted Meta latest Terms of Service (Settings > Help, or Settings > Application information will prompt them to accept the latest terms/policies if they haven't done so already)
Update to the latest version of the WhatsApp client

Type: Per-User Marketing Template Message Limits

Error code: 131049

Description: The message was not delivered to maintain a healthy ecosystem. See Per-User Marketing Template Message Limits.

Payload:

    ...
    "error_code": 131049,
    "error_details": "This message was not delivered to maintain healthy ecosystem engagement.",
    ...

Errors while messaging

400: Bad Request Check that you are using the correct data type for Booleans and Strings, and that the JSON-payload is well-formed. Use an online tool (ex. JSON formatter and validator) to validate the payload if you are not sure.

Recipient is not a valid WhatsApp user

This error occurs when the numbers you're trying to reach are not considered valid WhatsApp users, even though the numbers themselves are valid and accessible through wa.me link.

Meta acknowledges this bug, which can limit the reach of campaigns, and is working on a fix. We will share more information as soon as possible. Meanwhile, you can use the "/contacts" endpoint provided by the WhatsApp Business API as a workaround. See Meta's Official Documentation for On-premise and Cloud API hosting.

This endpoint allows you to verify if a user's WhatsApp account exists before sending messages, preventing errors and reducing "Recipient is not a valid WhatsApp user" responses. It's also recommended to implement robust error handling in your application, effectively capturing and parsing HTTP responses from the WhatsApp Business API. By identifying specific errors like "Recipient is not a valid WhatsApp user," you can handle them accordingly, either by excluding invalid numbers from the campaign or notifying the user about the issue.

408: Message failed to send because it was pending for too long There are no further details provided by WhatsApp. The recommendation is to resend the message.

470: Message failed to send because more than 24 hours have passed since the customer last replied to this number (no open session) Free-form text messages and media messages will result in a failure callback with error 470 when sent outside of the 24h-window. In other words, if it has been more than 24 hours since you last received a user initiated message - the session is closed and you can no longer use free-form messages. Please find a way to restrict message sending if there was no incoming message for the given user/phone number within 24h. Alternatively, you can contact the user using a Template Message.

1000: Failed to generate processed file path This could occur when the file storage is full and files cannot be stored. Please reach out to Help and Support.

1000: Image file format (audio/mpeg) is not supported Make sure that the message type matches the MIME-type of the file (ex. audio files should be sent using "audio", not "image"; audio/mpeg is an unsupported combination). Another reason could be that the video file doesn't have an audio track: then the error message contains something like video/mp4/h264/NONE where NONE is an indicator that the audio track is missing.

1006 - Unknown contact You did not use the v1/contacts endpoint to get a valid wa_id before sending the message. See the above guide on how to use the v1/contacts endpoint.

1009: Invalid latitude The valid range is from -90 to 90.

1014: Request for .... failed You have provided a URL that seems to be double URL-encoded and the file cannot be delivered because of that, or the file behind the URL doesn't exist.

2001: Template name does not exist in the translation The template needs to be set up by our Support team.

500: structure unavailable: Client could not display the highly structured message (hsm) The Template was not understood by the WhatsApp consumer client. Check the format.

WhatsApp API webhook errors

Error Code	Description	What to do
402	Message failed to send because there were one or more errors related to your payment method	Contact our support team and we will extend our Credit Line to your WABA.
429	Rate limit hit	For outgoing messages: Message failed to send because there were too many messages sent from this phone number in a short period of time. Resend the failed messages. For incoming messages: Failed to download media successfully due to rate-limiting. Ask the sender to resend the message.
470	Re-engagement message	Message failed to send because more than 24 hours have passed since the customer last replied to this number. Use a message template to respond.
471	Spam rate limit hit	Message failed to send because there are restrictions on how many messages can be sent from this phone number. This may be because too many previous messages were blocked or flagged as spam.
1011	Chat application is not initialized	This error occurs when you are trying to send a message on a number that is no longer registered for the WhatsApp API. A number can become unregistered for various reasons such as non compliance with the WhatsApp terms of service. If your number is unregistered, try to re-register the number or contact our support team.
1016	System overloaded	This error usually indicates that your webhook is not responding with status 200. This leads to a build up of webhooks in the DB and the system gets overloaded when the callback queue reaches 100K. Please check that your webhook is set and responding with status 200 for all incoming requests. This error may also indicate that the CoreApp is under heavy load. ie: it cannot handle the send message request volume. In that case, you should slow down the request volume and allow system to recover from the load.

Error Code

Description

What to do

402

Message failed to send because there were one or more errors related to your payment method

Contact our support team and we will extend our Credit Line to your WABA.

429

Rate limit hit

For outgoing messages: Message failed to send because there were too many messages sent from this phone number in a short period of time. Resend the failed messages.
For incoming messages: Failed to download media successfully due to rate-limiting. Ask the sender to resend the message.

470

Re-engagement message

Message failed to send because more than 24 hours have passed since the customer last replied to this number. Use a message template to respond.

471

Spam rate limit hit

Message failed to send because there are restrictions on how many messages can be sent from this phone number. This may be because too many previous messages were blocked or flagged as spam.

1011

Chat application is not initialized

This error occurs when you are trying to send a message on a number that is no longer registered for the WhatsApp API. A number can become unregistered for various reasons such as non compliance with the WhatsApp terms of service. If your number is unregistered, try to re-register the number or contact our support team.

1016

System overloaded

This error usually indicates that your webhook is not responding with status 200. This leads to a build up of webhooks in the DB and the system gets overloaded when the callback queue reaches 100K. Please check that your webhook is set and responding with status 200 for all incoming requests. This error may also indicate that the CoreApp is under heavy load. ie: it cannot handle the send message request volume. In that case, you should slow down the request volume and allow system to recover from the load.

PreviousCommon Issues NextImprint & Data Privacy

Last updated 2 months ago