Block Users API guide | Developer Documentation

Block Users API guide 
 Updated: Feb 23, 2026 
 The Block Users API enables your business to block bad actors from contacting you. 
 
 
 
 How it works 
 When you block a WhatsApp user, the following happens: The user cannot contact your business or see that you are online. Your business cannot message the user. If you do, you will encounter an error. 
 Errors on the API occur per-number since blocks might succeed on some numbers and fail on others. 
 The Block Users API is synchronous. 
 
 
 
 Limitations You can only block users that have messaged your business in the last 24 hours. You cannot use this API to block another WhatsApp Business account. The blocklist has a 64,000 user limit. 
 
 
 
 Features 
 The API contains three endpoints: 
 
 
 
 Error codes 
 
 
 
 
 Code 
 Description 
 
 
 
 
 139100 
 Failed to block/unblock some users 
 
 
 Bulk blocking failed to block some or all of the users. 
 
 
 
 139101 
 Blocklist limit reached 
 
 
 The blocklist has reached its 64,000 user limit. 
 
 
 
 139102 
 Blocklist concurrent update 
 
 
 Occurs when the blocklist is updated while performing a pagination request and version_id does not match. 
 
 
 
 139103 
 Internal error 
 
 
 Internal error, please try again. 
 
 
 
 130429 
 Rate Limit Hit 
 
 
 Occurs when either: Too many numbers are in the request itself. Or, too many requests are made over a short period of time. 
 
 
 
 131021 
 Self Block 
 
 
 Failed to block self phone number. 
 
 
 
 131047 
 Re-engagement required 
 
 
 Occurs if the business has not received a message from that number in the last 24 hours. 
 This error will also be returned if the number is an invalid WhatsApp user.