Skip to main content
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 with as much detail as possible — including any error codes or message IDs from your dashboard.

​
Message Delivery

Run through this checklist in order:
1

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.
2

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.
3

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.
4

Confirm the channel is enabled

Go to Settings > Channels and verify the channel you are using (SMS, WhatsApp, etc.) is active on your account.
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.
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 with the Message ID or Campaign ID from the report, and our team will investigate.
Include the message ID in your support request so our team can trace it through the delivery pipeline without delay.
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.
Repeatedly attempting to send to numbers that are not on WhatsApp will count against your messaging quota. Validate numbers before large campaigns.

​
API Errors

Your API key is missing, invalid, or revoked. To fix this:
1

Check the Authorization header

Confirm your request includes Authorization: Bearer <your-api-key> with no typos or extra whitespace.
2

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.
3

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.
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:
{
  "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.
You have exceeded the API rate limit for your account. Implement exponential backoff in your retry logic:
1

Respect the Retry-After header

The 429 response may include a Retry-After header (in seconds). Wait at least that long before retrying.
2

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.
3

Request a higher limit if needed

If your use case consistently requires a higher throughput, contact suporte@zexa.ao to discuss a volume plan.
A 400 error indicates that the request is structurally valid but contains an invalid value. Common causes include:
CauseFix
Phone number not in E.164 formatReformat to +<country code><number>, e.g. +244923000000
Unsupported channel valueUse one of: sms, whatsapp, telegram, email, slack
Sender ID not approvedApprove the Sender ID in Settings > Sender IDs first
Insufficient creditsTop up your balance in Billing > Top Up
Inspect the response body’s details field for the specific error message.
A 500 error indicates an unexpected problem on Zexa’s servers. These are rare and typically resolve within minutes.
1

Retry after a short wait

Wait 2–5 minutes and resend your request. Most 500 errors are transient.
2

Check the request ID

The response body includes a request_id field. Copy this value — it uniquely identifies your request in our logs.
3

Contact support if persistent

If the error continues after several retries, email suporte@zexa.ao with the request_id, the endpoint you called, and a sanitised copy of your request payload.

​
Account Access

1

Go to the login page

Navigate to https://app.zexa.ao and click Forgot password? below the sign-in form.
2

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.
3

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.
Check your spam folder if the email does not arrive within 5 minutes.
If you can no longer access your two-factor authentication device, contact 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.
Do not share your password or API keys in the support email. Our team will never ask for these.
When an account is suspended, Zexa sends an email to the registered address explaining the reason. Take the following steps:
1

Read the suspension notice

Review the email carefully to understand which policy was violated or which action triggered the suspension.
2

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.
3

Submit an appeal

Email 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. Our team will review your appeal within 2 business days.

​
Sender IDs

1

Read the rejection reason

Go to Settings > Sender IDs in the dashboard. Each rejected Sender ID displays a reason code and explanation.
2

Fix the issue

Common issues and their fixes:
Rejection reasonFix
Impersonation of a third-party brandUse your own registered brand name
Exceeds 11 charactersShorten to 11 characters or fewer
Contains spaces or special charactersRemove all spaces, hyphens, and special characters
3

Resubmit

Create a new Sender ID with the corrected value and submit it for review. Approval typically takes 1–3 business days.
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:
{
  "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.