Common errors#
HTTP errors#
| HTTP code | Error ID | Description |
|---|---|---|
| 204 | No Content | OPTIONS request method used, change the request method to GET |
| 400 | instance in starting process try later | The instance is in the process of starting/restarting. Please try again in a few seconds |
| 400 | instance is starting or not authorized | The instance is not authorized. To authorize the instance, go to the console and scan the QR code from the WhatsApp Business application on your phone |
| 400 | Instance account is expired. Renew your instance from personal area | The instance has expired. Renew your instance in the console |
| 400 | bad request data | The request data is not valid. Correct the error in the request parameters and try again |
| 400 | Instance is deleted | The instance has been deleted |
| 400 | Bad Request Validation failed | Validation error, more details in the table |
| 400 | Validation failed. Details: 'chatId' is required | The required parameter chatId (chat ID) is not specified. |
| 400 | Unexpected token _ in JSON at position XX | Error in the JSON structure |
| 401 | Unauthorized | Authorization problem, check that apiTokenInstance, partnerToken are specified correctly |
| 403 | Forbidden | Authentication problem, check that idInstance and the request URL are specified correctly |
| 404 | Not Found | Invalid request method |
| 429 | Too Many Requests | The user has sent too many requests in a given period of time. Reduce the request frequency. Request frequency guidelines |
| 466 | correspondentsStatus | The limit has been reached, more details in the error body. Error body example |
| 499 | Client Closed Request | The user closed the connection while the server was processing the request. Increase the timeout for the server response and repeat the request with a delay. If the error persists, inform the operator and provide an opportunity to retry the submission |
| 500 | File from url exceeded max upload size. Size: XXXXmb Limit: 100mb Url: | An attempt to send a file larger than 100 MB |
| 500 | request entity too large | The allowed JSON length has been exceeded (>100 KB) |
| 502 | Bad Gateway | The server is unable to receive a response from the target server. Repeat the request 3 times with a delay. If the error persists, inform the operator and provide an opportunity to retry the submission |
Errors in the webhooks body and journals#
| Error code | Parameter | Description | Solution |
|---|---|---|---|
| {{SWE001}} | textMessage | Error of receiving the first incoming message in the chat when it is sent to additional devices from the WhatsApp side. It is also observed in the native web and desktop versions. In fact, all additional devices get an empty message. Webhook body example | Catch the text marker {{SWE001}} in the message body and configure the bot to re-request the message from the sender with the text: "Please send your message again, I couldn't see your reply" |
| {{SWE002}} | downloadUrl | Error of getting a large file over 100 MB. Webhook body example | Catch the text marker {{SWE002}} in the message body and check the message on the phone |
| {{SWE003}} | textMessage | Error of decrypting messages caused by outdated authorization keys. Webhook body example | Catch the text marker {{SWE003}}. When such messages appear, delete all authorizations on the phone and scan the QR code again |
| {{SWE004}} | textMessage | Error working with group chats caused by exceeding the limit of 1024 contacts in a group. Webhook body example | Catch the text marker {{SWE004}}. When such messages appear, delete the groups with more than 1024 participants or remove contacts from the groups |
| {{SWE005}} | textMessage | Notification of receiving a one-time audio or video message in a private or group chat. Webhook body example | Catch the text marker {{SWE005}}. View the message on the primary device. There may be false SWE001 errors if the user has changed the chat settings. For messages without a body, SWE001 is generated. |
| {{SWE999}} | textMessage | Error of receiving an incoming message without encryption keys in the chat from the WhatsApp side. In fact, all additional devices get an empty message. Webhook body example | When such messages appear, delete all authorizations on the phone and scan the QR code again |
Validation errors (400: Validation failed)#
| Error ID | Description |
|---|---|
'chatId' must be one of the next formats: 'phone_number@c.us' or 'group_id@g.us | Invalid format of the chatId field, the field is specified in the format phone_number@c.us or group_id@g.us |
'wrongFieldName' is not allowed | Invalid field in the request body |
'{{field}}' is not allowed | Invalid field in the request body |
'{{field}}' is required | A required field is missing in the request body |
'{{field}}' is not allowed to be empty | A required field cannot be empty |
'message id' must be at least 16 symbols | The ID of the quoted message must be at least 16 characters long, check that the specified idmessage or quotedMessageId is correct |
'XXX' must be a string | Invalid data type of the XXX field - the field must be of type string. Fields of this type: message, idMessage,quotedMessageId, groupId, groupName, participantChatId, options[X].optionName, urlFile |
'XXX' must be a boolean | Invalid data type of the XXX field - the field must be of type boolean. Fields of this type: linkPreview, multipleAnswers |
'XXX' must be an array | Invalid data type of the XXX field - the field must be of type array. Fields of this type: chatIds, options, messages |
