Error and Status Messages

This document provides more information about the following types of error and status messages:

WhatsApp Business API Client Error Codes

Error CodeTitleDescription

400

Media download error

Failed to download the media from the sender

401

Group does not exist

Failed to send message because the group doesn't exist.

402

Business eligibility — Payment issue

  • Payment account is not attached to a WhatsApp Account
  • Credit line is over the limit
  • Credit line (Payment account) not set or active
  • WhatsApp Business Account is deleted
  • Account has been suspended by us
  • Timezone not set
  • Currency not set
  • MessagingFor request (OBO) is pending or declined

408

Message is not valid

Failed to send message because it was too old.

410

Message expired

Message failed to send during its Time To Live (TTL) duration.

429

Rate limit hit

Sender rate limit has been hit (server-side)

430

Unsigned Verified Name certificate

Occurs when a message is sent while the business does not have a valid, signed Verified Name certificate set on the server.

432

Verified Name certificate ID mismatch

Occurs when a message is sent but the business client's Verified Name certificate ID included in the message doesn't match what's been set on the server.

433

Verified Name certificate signature invalid

Occurs when a message is sent but the business client's Verified Name is not properly signed using the client's identity keys. This likely indicates that the client re-registered with new identity keys but did not go through the full cert creation flow.

470

Re-engagement message

Non-Message Template message sent more than 24 hours after the customer last messaged the business.

471

Spam Rate limit hit

Sender spam rate limit has been hit.

472

User's number is part of an experiment

WhatsApp runs experiments to measure and understand the impact of Business API notifications on user experience and the overall product in general. The recipient of this message is in one of these experiments, so will not receive notifications from you even if they have opted in.

500

Generic error

A generic error occurred, see the "details" key in the error object for more specific info.

1000

Generic error

1001

Message too long

Message length exceeds 4096 characters.

1002

Invalid recipient type

Valid recipient types are:


  • individual
  • group

1003

Not a group participant

User is not a participant of the group.

1004

Resource already exists

Possible UUID conflict for media upload request or media with that UUID already exists.

1005

Access denied

  • Media directory is not writable (upload request) or
  • Invalid credentials or
  • VName Certificate Error or
  • App Expired: a version upgrade is required

1006

Resource not found

File or resource not found

1007

Recipient blocked to receive message

Recipient is not whitelisted

1008

Required parameter is missing

Missing a required parameter

1009

Parameter value is not valid

Value entered for a parameter is of the wrong type or other problem.

1010

Parameter is not required

Contains a parameter that is not required.

1011

Service not ready

1012

Group is unknown

You will receive this error when you send messages to a group in which you are the only member. Add some members to the group before sending messages.

1013

User is not valid

1014

Internal error

Upload failed on bad image (image not uploaded correctly) or endpoint not found

1015

Too many requests

Client-side rate limit has been hit

1016

System overloaded

If the system is under heavy load, this error is returned to allow the system to recover from the load.

1017

Not Primary Master

You receive this error when a master-only request, such as set settings, get settings, import, export, code request, register, etc. is sent to a node that is not a primary master. This could happen when the WhatsApp Business API Client is not setup properly or internal errors.
Retrying the request should resolve this error most of time. If not, please contact us for support.

1018

Not Primary Coreapp

You receive this error when requests are sent to a Coreapp node that is not the shard owner or in the process to become the shard owner. You might see this error when we are doing shard failover in the multiconnect setup.


Retrying the request should resolve this error most of time. If not, please contact Support.

1019

Not a group admin

1020

Bad group

1021

Bad User

You will receive this message when you send a message to yourself.
To resolve, send the message to number that is not your own.

1022

Webhooks URL is not configured

You will receive this error if you have not configured the REST API Webhooks format.

1023

Database error occurred

HTTP Status Codes

These are HTTP Status Codes that could be used by the WhatsApp Business API Client.

HTTP CodeDescription

2xx

Success

200

Success (OK)

201

Successfully created (For POST requests)

302

Found

4xx

Client Errors

400

Request was invalid

401

Unauthorized

403

Forbidden

404

Not found

405

Method not allowed.

412

Precondition failed

420

Message is rate limited

429

Too many requests

5xx

Server Errors

500

Internal server error

504

Timeout