Skip to main content

​
API Troubleshooting

This guide covers common errors, HTTP status codes, and solutions for issues you may encounter when integrating with the Zeplo API. If you cannot resolve an issue using this guide, contact our support team at support@zeplo.ai.

​
Common Error Categories

Authentication Errors

Invalid or missing API keys, expired sessions, and insufficient permissions. Usually return 401 or 403 status codes.

Rate Limiting

Requests exceeding your plan’s rate limits. Returns 429 status with a Retry-After header indicating when to retry.

Validation Errors

Malformed request bodies, invalid phone numbers, missing required fields, or incorrect parameter types. Returns 400 or 422.

Server Errors

Unexpected server-side failures, upstream WhatsApp API errors, or temporary service unavailability. Returns 500, 502, or 503.

​
Error Response Format

All Zeplo API errors return a consistent JSON structure:
The details object is optional and may contain additional context specific to the error. Not all error responses include it. Always check the message field first as it contains the human-readable explanation.

​
HTTP Status Codes

​
Common Issues

Symptom: API returns 400 with INVALID_PHONE_NUMBER.Cause: Phone numbers must be in E.164 format without spaces, dashes, or a leading +. Example: 919876543210 (not +91 98765 43210).Solution: Strip all non-digit characters and ensure the number includes the country code.
Symptom: Sending a template message returns 400 with INVALID_TEMPLATE.Cause: The template has not been approved by WhatsApp, has been rejected, or the template name or language code does not match.Solution: Check the template status via the Templates API or Settings > Templates in the dashboard. Ensure the templateName and languageCode match exactly. Note that template names are case-sensitive.
Symptom: Messages fail with 502 or you see “Channel Disconnected” in the dashboard.Cause: The access token for your WhatsApp Business Account has expired or been revoked. This can happen if you changed your Facebook password, revoked app permissions, or the token expired after its validity period.Solution: Go to Settings > Channels in the Zeplo dashboard and click Reconnect on the affected channel. Follow the Embedded Signup flow to restore the connection.
Symptom: You configured a webhook URL but are not receiving POST requests from Zeplo.Cause: Common causes include an incorrect URL, a server returning non-200 responses, SSL certificate issues, or firewall rules blocking Zeplo’s IP addresses.Solution: Verify your webhook URL returns a 200 status for POST requests. Ensure your SSL certificate is valid and not self-signed. Check your server logs for incoming requests from Zeplo. Use the Test Webhook button in Settings > Webhooks to send a test event.
Symptom: API requests are taking longer than expected to complete.Cause: Sending messages through Zeplo involves an upstream call to Meta’s Cloud API. Latency may increase during peak usage periods or if Meta’s API is experiencing delays. Large batch operations can also increase response times.Solution: For non-urgent bulk operations, use the batch API endpoints which process asynchronously. Check the X-Response-Time response header to distinguish between Zeplo processing time and upstream latency. If response times consistently exceed 5 seconds, contact support.
Symptom: The API returns a 200 status and a message ID, but the recipient never receives the message.Cause: The recipient’s phone number may not be registered on WhatsApp, the recipient may have blocked your number, or the message may be caught in WhatsApp’s spam filter. Template messages sent outside the 24-hour window with incorrect parameters can also fail silently.Solution: Check the message status via the Messages API using the returned messageId. Status values include sent, delivered, read, and failed. A failed status will include a reason code. Verify the recipient’s phone number is an active WhatsApp account.

​
Need More Help?

If you cannot resolve your issue using this guide, reach out to our support team:When contacting support, include your API request (with the key redacted), the full error response, and the X-Request-Id header value. This helps us investigate faster.