Error Codes

Complete reference of error codes, HTTP statuses, and what they mean for your integration.

Error Response Format

All API errors return a consistent JSON structure:

JSON

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "status": 401
  }
}

Code	HTTP	Description
INVALID_API_KEY	401	API key is invalid, expired, or revoked
INSUFFICIENT_SCOPE	403	API key lacks required permission
RATE_LIMITED	429	Too many requests for your tier
CLIENT_NOT_FOUND	404	The client_ref does not match any client
CLIENT_DISCONNECTED	400	The client's WhatsApp is disconnected
INVALID_PHONE	400	The recipient phone number is invalid
TEMPLATE_NOT_FOUND	404	The template name was not found
MESSAGE_FAILED	502	Meta API rejected the message
WEBHOOK_URL_MISSING	400	No webhook URL configured
VALIDATION_ERROR	400	Request body failed validation
INTERNAL_ERROR	500	An unexpected error occurred

Docs/Error Codes

Complete reference of error codes, HTTP statuses, and what they mean for your integration.

All API errors return a consistent JSON structure:

JSON

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "status": 401
  }
}

Code	HTTP	Description
INVALID_API_KEY	401	API key is invalid, expired, or revoked
INSUFFICIENT_SCOPE	403	API key lacks required permission
RATE_LIMITED	429	Too many requests for your tier
CLIENT_NOT_FOUND	404	The client_ref does not match any client
CLIENT_DISCONNECTED	400	The client's WhatsApp is disconnected
INVALID_PHONE	400	The recipient phone number is invalid
TEMPLATE_NOT_FOUND	404	The template name was not found
MESSAGE_FAILED	502	Meta API rejected the message
WEBHOOK_URL_MISSING	400	No webhook URL configured
VALIDATION_ERROR	400	Request body failed validation
INTERNAL_ERROR	500	An unexpected error occurred