Errors

A failed request has an HTTP status that says what kind of failure it is, and a code that says exactly which. Branch on the code; show or log the message.

Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "to: Recipient phone is required",
    "details": [
      {
        "field": "to",
        "message": "Recipient phone is required"
      }
    ]
  }
}

message is written to be read by a person and may change wording over time, so do not match on it. details appears only on some errors.

Codes

Status	Code	Meaning	Retry?
400	`BAD_REQUEST`	The request was understood but cannot be done: the template is not approved, a button value is missing, WhatsApp refused the message. The message says which.	No. Fix the request.
400	`HEADER_MEDIA_REQUIRED`	The template has an image, video or document header and the send had no `headerMediaUrl`.	No. Add the link.
400	`NO_OPEN_CONVERSATION`	A reply was sent outside the 24-hour window.	No. Send a template instead.
400	`MEDIA_TOO_LARGE`	The file is over 16 MB.	No.
400	`MEDIA_FETCH_FAILED`	Downloading the file link failed, for example it answered 404.	Only after fixing the link.
400	`MEDIA_URL_REJECTED`	The file link points somewhere we will not fetch from, such as a private address.	No.
401	`API_KEY_MISSING`	No key was sent.	No.
401	`API_KEY_INVALID`	The key is wrong or revoked.	No.
401	`API_KEY_EXPIRED`	The key passed its expiry date.	No. Create a new key.
403	`API_KEY_IP_NOT_ALLOWED`	The call came from an address the key does not allow. The message names the address.	No. Add the address to a new key, or call from an allowed one.
401	`WORKSPACE_SUSPENDED`	The workspace is suspended.	No.
402	`WALLET_INSUFFICIENT`	The workspace pays through the Wamafy wallet and the balance cannot cover the message. Nothing was sent or charged.	Not on a timer. Resume once the wallet is topped up.
403	`API_SCOPE_MISSING`	The key lacks the scope this endpoint needs.	No. Add the scope or use another key.
403	`API_QUOTA_EXCEEDED`	The plan's monthly API call allowance is used up.	Next month, or after an upgrade.
403	`CAPACITY_LIMIT_REACHED`	Creating this would go over a plan limit, such as contacts or campaigns a month.	No.
404	`NOT_FOUND`	Nothing by that name or id in your workspace: template, number, contact, campaign, message.	No.
422	`VALIDATION_ERROR`	A field is missing or the wrong type. `details` lists each one.	No. Fix the request.
429		Too many requests. Each key may make 60 a minute.	Yes, after the number of seconds in the `Retry-After` header.
500, 502, 503		Something failed on our side or at WhatsApp.	Yes, with a growing delay (1s, 2s, 4s and so on).

WhatsApp delivery failures

A message can be accepted (status: "sent") and still fail on the way to the phone. That shows up later, in Get message status or the status webhook, with WhatsApp's own code. The common ones:

Code	What it means
`131026`	The number is not on WhatsApp, or the person has blocked you. Stop sending to it.
`131049`	WhatsApp held back a marketing message to protect the person from too many. It is not an error in your request; try again another day, or reach them when they next write to you.
`131047`	The 24-hour window had closed by the time the reply went out. Send a template.
`132000`, `132012`	The template's variables or buttons did not match what was approved.