> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeplo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose and resolve common issues when working with the Zeplo API.

## 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](mailto: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:

```json theme={null}
{
  "error": "Authentication Error",
  "message": "The API key provided is invalid or has been revoked. Please generate a new key from Settings > API Keys.",
  "code": "INVALID_API_KEY",
  "details": {
    "providedKey": "zk_****... truncated",
    "suggestion": "Verify your API key or create a new one at https://app.zeplo.ai/settings/api-keys"
  }
}
```

> [!NOTE]
>
> 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

| Status | Name | Description | Solution |
| - | - | - | - |
| `400` | Bad Request | The request body is malformed or contains invalid parameters | Check the `message` and `details` fields. Verify all required fields are present and values match expected formats. |
| `401` | Unauthorized | Authentication failed — missing, invalid, or revoked API key | Verify your `x-api-key` header is correct. Regenerate the key in **Settings > API Keys** if needed. |
| `403` | Forbidden | Your API key lacks the required permission for this action | Check the permissions assigned to your API key. An admin can update permissions from the dashboard. |
| `404` | Not Found | The requested resource does not exist | Verify the resource ID in your URL path. The channel, contact, or template may have been deleted. |
| `429` | Rate Limited | You have exceeded your plan's request rate limit | Wait for the number of seconds in the `Retry-After` header, then retry. Consider upgrading your plan for higher limits. |
| `500` | Internal Server Error | An unexpected error occurred on Zeplo's servers | Retry the request after a short delay. If the error persists, contact [support@zeplo.ai](mailto:support@zeplo.ai) with the request ID from the response headers. |
| `502` | Bad Gateway | Zeplo received an error from the upstream WhatsApp API | This is typically a temporary issue. Retry after a few seconds. Check [Meta's status page](https://metastatus.com) for known outages. |
| `503` | Service Unavailable | Zeplo is temporarily unavailable due to maintenance or overload | Retry after the duration specified in the `Retry-After` header. Check our status page for maintenance announcements. |

## Common Issues

> **Invalid phone number format**
>
> **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.
>
> ```typescript theme={null}
> function formatPhone(phone: string): string {
>   return phone.replace(/\D/g, '').replace(/^0+/, '');
> }
>
> formatPhone('+91 98765 43210'); // "919876543210"
> ```

> **Template not approved or not found**
>
> **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.

> **WhatsApp channel disconnected**
>
> **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.

> **Webhook not receiving events**
>
> **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.

> **Slow API responses**
>
> **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.

> **Message sent but not delivered**
>
> **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?

> [!NOTE]
>
> If you cannot resolve your issue using this guide, reach out to our support team:
>
> * **Email:** [support@zeplo.ai](mailto:support@zeplo.ai)
> * **Dashboard:** [app.zeplo.ai/support](https://app.zeplo.ai/support)
> * **API Status:** Check our status page for real-time service availability and incident reports
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.