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

# Zexa Troubleshooting Guide: Fix Common Issues Fast

> Diagnose and fix common issues with Zexa — message delivery failures, API errors, Sender ID rejections, and account access problems, step by step.

Most issues with Zexa fall into a handful of predictable categories: delivery failures, API errors, account access problems, and Sender ID rejections. Work through the relevant section below to identify and resolve your issue quickly. If a problem persists after following these steps, contact [suporte@zexa.ao](mailto:suporte@zexa.ao) with as much detail as possible — including any error codes or message IDs from your dashboard.

***

## Message Delivery

<AccordionGroup>
  <Accordion title="Messages are not being delivered">
    Run through this checklist in order:

    <Steps>
      <Step title="Check your credit balance">
        Go to **Billing > Overview**. If your balance is zero or below the cost of the message, sending is paused. Top up your balance to resume.
      </Step>

      <Step title="Verify the recipient phone number format">
        All phone numbers must be in **E.164 format** — a `+` sign followed by the country code and number, with no spaces or dashes (e.g., `+244923000000`). Requests with incorrectly formatted numbers are rejected silently at the carrier level.
      </Step>

      <Step title="Confirm your Sender ID is approved">
        Navigate to **Settings > Sender IDs** and check the status. A Sender ID with a **Pending** or **Rejected** status cannot be used to send messages.
      </Step>

      <Step title="Confirm the channel is enabled">
        Go to **Settings > Channels** and verify the channel you are using (SMS, WhatsApp, etc.) is active on your account.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="SMS was marked 'Delivered' but the recipient did not receive it">
    A `delivered` status means the message was accepted by the carrier network, but a small number of scenarios can still prevent it from appearing on the device:

    * The recipient's number may be registered on a **do-not-disturb** or spam-filter list maintained by their carrier.
    * The carrier may have **filtered** the message due to content heuristics.
    * The recipient's device may have been **switched off or unreachable** at the moment of delivery, and the carrier's retry window may have expired.

    Check the full delivery report in **Campaigns > Reports** for carrier-level status codes. If the pattern repeats across multiple recipients, review your message content against the [compliance guidelines](/help/compliance).
  </Accordion>

  <Accordion title="Delivery status is stuck on 'Queued'">
    A `queued` status usually resolves within a few minutes. During high-traffic periods, SMS delivery can take up to **30 minutes**. If the status has not updated after **1 hour**:

    1. Refresh the campaign report in **Campaigns > Reports**.
    2. Verify your Sender ID is still approved.
    3. Contact [suporte@zexa.ao](mailto:suporte@zexa.ao) with the **Message ID** or **Campaign ID** from the report, and our team will investigate.

    <Note>
      Include the message ID in your support request so our team can trace it through the delivery pipeline without delay.
    </Note>
  </Accordion>

  <Accordion title="WhatsApp message failed to send">
    Check both of the following:

    * **Recipient has WhatsApp installed and active** on that number. If the number is not registered with WhatsApp, the message cannot be delivered.
    * **Template requirement** — if you are initiating a conversation (not replying within a 24-hour service window), you must use an approved WhatsApp message template. Free-form messages sent outside a session window will fail. Submit or review templates in **Settings > Templates**.

    <Warning>
      Repeatedly attempting to send to numbers that are not on WhatsApp will count against your messaging quota. Validate numbers before large campaigns.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## API Errors

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Your API key is **missing, invalid, or revoked**. To fix this:

    <Steps>
      <Step title="Check the Authorization header">
        Confirm your request includes `Authorization: Bearer <your-api-key>` with no typos or extra whitespace.
      </Step>

      <Step title="Verify the key has not been revoked">
        Go to **Settings > API Keys** in the dashboard. If the key is listed as revoked, generate a new one.
      </Step>

      <Step title="Store the key correctly">
        The full API key is only shown once at generation time. If you lost it, revoke the old key and generate a replacement.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="422 Unprocessable Entity">
    The request body is **malformed or missing a required field**. The response body will contain a `details` array that identifies each problematic field. For example:

    ```json theme={null}
    {
      "error": "unprocessable_entity",
      "details": [
        { "field": "to", "message": "is required" },
        { "field": "channel", "message": "must be one of: sms, whatsapp, telegram, email, slack" }
      ]
    }
    ```

    Correct the fields listed in `details` and resend the request.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    You have exceeded the **API rate limit** for your account. Implement exponential backoff in your retry logic:

    <Steps>
      <Step title="Respect the Retry-After header">
        The 429 response may include a `Retry-After` header (in seconds). Wait at least that long before retrying.
      </Step>

      <Step title="Implement exponential backoff">
        Start with a 1-second wait, then double the interval on each subsequent 429 response (1 s → 2 s → 4 s → 8 s, etc.) up to a reasonable maximum.
      </Step>

      <Step title="Request a higher limit if needed">
        If your use case consistently requires a higher throughput, contact [suporte@zexa.ao](mailto:suporte@zexa.ao) to discuss a volume plan.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="400 Bad Request">
    A 400 error indicates that the request is structurally valid but contains an invalid value. Common causes include:

    | Cause                            | Fix                                                         |
    | -------------------------------- | ----------------------------------------------------------- |
    | Phone number not in E.164 format | Reformat to `+<country code><number>`, e.g. `+244923000000` |
    | Unsupported `channel` value      | Use one of: `sms`, `whatsapp`, `telegram`, `email`, `slack` |
    | Sender ID not approved           | Approve the Sender ID in **Settings > Sender IDs** first    |
    | Insufficient credits             | Top up your balance in **Billing > Top Up**                 |

    Inspect the response body's `details` field for the specific error message.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    A 500 error indicates an unexpected problem on **Zexa's servers**. These are rare and typically resolve within minutes.

    <Steps>
      <Step title="Retry after a short wait">
        Wait 2–5 minutes and resend your request. Most 500 errors are transient.
      </Step>

      <Step title="Check the request ID">
        The response body includes a `request_id` field. Copy this value — it uniquely identifies your request in our logs.
      </Step>

      <Step title="Contact support if persistent">
        If the error continues after several retries, email [suporte@zexa.ao](mailto:suporte@zexa.ao) with the `request_id`, the endpoint you called, and a sanitised copy of your request payload.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Account Access

<AccordionGroup>
  <Accordion title="I forgot my password">
    <Steps>
      <Step title="Go to the login page">
        Navigate to [https://app.zexa.ao](https://app.zexa.ao) and click **Forgot password?** below the sign-in form.
      </Step>

      <Step title="Enter your email address">
        Submit the email address associated with your Zexa account. A password reset link will be sent to that address within a few minutes.
      </Step>

      <Step title="Use the reset link promptly">
        The reset link is valid for **1 hour**. If it expires, return to the login page and request a new one.
      </Step>
    </Steps>

    <Note>
      Check your spam folder if the email does not arrive within 5 minutes.
    </Note>
  </Accordion>

  <Accordion title="I am locked out after losing my 2FA device">
    If you can no longer access your two-factor authentication device, contact [suporte@zexa.ao](mailto:suporte@zexa.ao) to begin the account recovery process. Include the following in your request:

    * The **email address** on the account
    * Your **company NIF** (or personal Bilhete de Identidade number for individual accounts)
    * A clear **description of the situation** and how access was lost

    Our support team will verify your identity and guide you through recovery. For security reasons, we cannot bypass 2FA without identity verification.

    <Warning>
      Do not share your password or API keys in the support email. Our team will never ask for these.
    </Warning>
  </Accordion>

  <Accordion title="My account has been suspended">
    When an account is suspended, Zexa sends an email to the registered address explaining the reason. Take the following steps:

    <Steps>
      <Step title="Read the suspension notice">
        Review the email carefully to understand which policy was violated or which action triggered the suspension.
      </Step>

      <Step title="Review your messaging activity">
        Check **Campaigns > Reports** and **Contacts > Opt-Outs** for signs of policy violations, such as high complaint rates or sending to opted-out contacts.
      </Step>

      <Step title="Submit an appeal">
        Email [suporte@zexa.ao](mailto:suporte@zexa.ao) with a summary of the steps you have taken to resolve the issue and a commitment to comply with the [Terms of Use](https://app.zexa.ao/terms). Our team will review your appeal within 2 business days.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Sender IDs

<AccordionGroup>
  <Accordion title="My Sender ID was rejected">
    <Steps>
      <Step title="Read the rejection reason">
        Go to **Settings > Sender IDs** in the dashboard. Each rejected Sender ID displays a reason code and explanation.
      </Step>

      <Step title="Fix the issue">
        Common issues and their fixes:

        | Rejection reason                      | Fix                                                |
        | ------------------------------------- | -------------------------------------------------- |
        | Impersonation of a third-party brand  | Use your own registered brand name                 |
        | Exceeds 11 characters                 | Shorten to 11 characters or fewer                  |
        | Contains spaces or special characters | Remove all spaces, hyphens, and special characters |
      </Step>

      <Step title="Resubmit">
        Create a new Sender ID with the corrected value and submit it for review. Approval typically takes 1–3 business days.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="My Sender ID is approved but messages show a different sender">
    This usually means the `from` field in your API request or campaign does not exactly match the approved Sender ID. Sender IDs are **case-sensitive** and must be an exact character-for-character match.

    Verify the approved string in **Settings > Sender IDs** and ensure your API request passes it exactly:

    ```json theme={null}
    {
      "from": "MyBrand"
    }
    ```

    A value of `mybrand` or `MYBRAND` will not match an approved `MyBrand` Sender ID, and your message will either fail or be sent with a fallback numeric ID.
  </Accordion>
</AccordionGroup>