Error Codes

When an API request fails, WaConnect returns a JSON error response with an HTTP status code and a descriptive message. This page lists common errors and how to resolve them.

Error Response Format

{
  "success": false,
  "error": "Description of the error"
}JSON

WaConnect Errors

These errors are returned by the WaConnect platform itself:

HTTP Status	Error	Cause	Resolution
400	Missing required field	A required field (e.g., to, body) is missing from the request body.	Check the endpoint documentation and include all required fields.
400	Invalid phone number format	The to field is not a valid phone number.	Use the full international format without + or spaces (e.g., "15551234567").
401	Missing API Key	The X-API-Key header was not included.	Add the X-API-Key header to your request.
401	Invalid API Key	The API key does not match any active account.	Verify your API key is correct. Contact your admin if needed.
403	Account disabled	Your account has been deactivated.	Contact your administrator to reactivate your account.
403	Phone number not authorized	The phoneNumberId you specified is not assigned to your account.	Use a phone number that is assigned to your account, or omit the field to use the default.
404	Message not found	The message ID does not exist or does not belong to your account.	Verify the message ID is correct.
500	Internal server error	An unexpected error occurred on the platform.	Retry the request. If the error persists, contact your administrator.

Meta / WhatsApp API Errors

These errors originate from the Meta Cloud API and are passed through by WaConnect:

Meta Error Code	Meaning	Resolution
131030	Recipient phone number not on WhatsApp	The recipient has not registered this number with WhatsApp.
131047	Re-engagement message required	More than 24 hours since the customer's last message. Use a message template instead.
131051	Unsupported message type	The message type or format is not supported. Check the payload structure.
131053	Media upload error	The media URL is not accessible or the file format is unsupported.
130429	Rate limit exceeded	Too many requests. Implement exponential backoff and retry.
132000	Template not found or not approved	The template name or language code is incorrect, or the template has not been approved yet.
133010	Phone number not registered	The sending phone number is not properly registered for Cloud API use.

Troubleshooting Tips

• Use the Chat Simulator to test messages before integrating with code.
• Check the Swagger UI for the exact expected payload format of each endpoint.
• If you receive a 131047 error, the 24-hour messaging window has expired. You must use an approved message template to re-initiate the conversation.
• Ensure media URLs are publicly accessible (no authentication required) and use HTTPS.
• Phone numbers must be in international format without the + prefix.