API Reference v1.0

Error Codes Reference

Complete reference of error codes returned by the WhatsBizAPI API.

HTTP Status Codes

Every API response includes a standard HTTP status code indicating the result of the request.

Code	Meaning
200	Success — the request completed successfully.
400	Bad Request — the request contains invalid or missing parameters.
401	Unauthorized — the API token is invalid or missing.
402	Payment Required — your subscription has expired or you have insufficient credits.
404	Not Found — the requested resource does not exist.
429	Rate Limit Exceeded — too many requests in a given time period. Retry after the indicated wait time.
`500`	Internal Server Error — an unexpected error occurred on the server. Contact support if this persists.

Authentication Errors

Authentication errors occur when your API token is invalid, expired, or lacks the necessary permissions.

Code	Title	Description
`0`	Auth Exception	The access token is invalid or has expired. Generate a new token from your dashboard under Settings → API.
`10`	Permission Denied	Your account does not have the required permission for this operation. Check your plan and API scope settings.
`190`	Token Expired	The API token has expired and needs to be renewed. Regenerate the token from your dashboard.

Example Authentication Error Response

{
  "status": "error",
  "error": {
    "code": 190,
    "title": "Token Expired",
    "message": "The access token has expired. Please generate a new token."
  }
}

Message Errors

These errors are returned when a message fails to send due to invalid parameters, recipient issues, or policy violations.

Code	Title	Description
`131008`	Required parameter missing	A required field is missing from the request body. Check the endpoint documentation for required parameters.
`131009`	Invalid parameter	A parameter value is malformed or out of the accepted range. Verify the data types and formats of your parameters.
`131026`	Message undeliverable	The recipient phone number is not registered on WhatsApp. Verify the number is correct and active on the platform.
`131047`	Re-engagement required	More than 24 hours have passed since the recipient last replied. You must use an approved template message to re-initiate the conversation.
`131048`	Spam rate limit	Too many of your messages have been flagged as spam by recipients. Reduce sending frequency and review your message content.
`131050`	Marketing opt-out	The recipient has opted out of receiving marketing messages from your business. Respect their preference and remove them from marketing lists.
`131051`	Unsupported message type	The message type or format is not supported for this recipient or conversation context.

Example Message Error Response

{
  "status": "error",
  "error": {
    "code": 131047,
    "title": "Re-engagement required",
    "message": "More than 24 hours have passed since the recipient's last message. Use a template message."
  }
}

Template Errors

Template errors are returned when sending a template message with incorrect parameters, or when the template itself is unavailable.

Code	Title	Description
`132000`	Parameter count mismatch	The number of variables provided does not match the number of placeholders in the template. Verify your template and parameters align.
`132001`	Template not found	The specified template does not exist or has not been approved. Check the template name, language code, and approval status.
`132015`	Template paused	This template has been paused due to a low quality score. Improve the template content or wait for Meta to lift the restriction.
`132016`	Template disabled	This template has been permanently disabled and cannot be used. You will need to create and submit a new template.

Example Template Error Response

{
  "status": "error",
  "error": {
    "code": 132001,
    "title": "Template not found",
    "message": "Template 'order_update' in language 'en' was not found or is not approved."
  }
}

Rate Limit Errors

Rate limit errors indicate that you have exceeded the allowed number of requests or messages within a given time window.

Code	Title	Description
`4`	Too Many Calls	Your application has reached its API call rate limit. Wait and retry with exponential backoff.
`80007`	Rate limit	Your WhatsApp Business Account has reached its rate limit. Reduce request frequency and spread calls over time.
`130429`	Throughput limit	Message throughput has been exceeded. Your account is sending messages faster than the allowed rate. Implement queuing and throttling.
`131056`	Pair rate limit	Too many messages have been sent to the same recipient in a short period. Space out messages to the same number.

Example Rate Limit Error Response

{
  "status": "error",
  "error": {
    "code": 130429,
    "title": "Throughput limit",
    "message": "Message throughput has been exceeded. Please retry after reducing your sending rate."
  }
}

Handling Errors

ℹ

Tip: When you receive an error, check the error code and message for specific guidance. Most errors include actionable details that tell you exactly what went wrong and how to fix it.

✓

Best practice: Always implement structured error handling in your integration. Parse the error.code field to determine the appropriate recovery action, and log the full error response for debugging.

Error Handling Example (JavaScript)

const response = await fetch('/api/wpbox/sendmessage', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token, phone, message })
});

const data = await response.json();

if (data.status === 'error') {
  switch (data.error?.code) {
    case 131047:
      // Re-engagement required: send a template message instead
      await sendTemplateMessage(phone, templateName, params);
      break;
    case 130429:
    case 4:
      // Rate limited: wait and retry with exponential backoff
      await delay(retryAfterMs);
      await retrySendMessage(phone, message);
      break;
    case 190:
      // Token expired: refresh the token
      await refreshApiToken();
      break;
    default:
      console.error('API Error:', data.error);
  }
}