Skip to main content
Version: 1.0

Troubleshooting

Authentication errors​

401 Unauthorized​

CauseHow to fix
x-api-key header missingAdd the header to all requests
Incorrect key valueCheck for extra spaces or hidden characters
Key belongs to another ApplicationUse the correct key for the Application that contains the channel
Key revokedGenerate a new key in the Hub Chatt2.me dashboard under Settings → API Key

Payload errors​

400 Bad Request​

Occurs when the request body is invalid. Most common causes:

CauseError example
Required field missingfrom, to, or content not provided
Incorrect type for content fieldSent imageUrl but the channel does not support images
Invalid format for to fieldWhatsApp expects E.164 without +, SMS expects with +
Invalid field combination in contentUsing template + components with ORDER_STATUS template
Invalid interactive.type for the channelType location_request_message only exists on WhatsApp

How to diagnose: check the response body — it usually includes a descriptive message explaining what is wrong.

Resource not found errors​

404 Not Found​

CauseHow to fix
Incorrect channel UUID (from)Check the UUID in the Channels section of the Application dashboard
Channel disconnected or deletedReconnect the channel in the Hub Chatt2.me dashboard
Channel belongs to another ApplicationEach key only accesses channels from its own Application
Invalid webhookIdCheck the ID with GET /v1/organization/webhook
Invalid webhookLogIdCheck the ID with GET /v1/organization/webhook/{id}/webhook-log

Message sending issues​

The message returned status: error​

Check the errorMessage and errorCode fields in the response:

{
  "messageId": null,
  "status": "error",
  "errorMessage": "The recipient is not a valid WhatsApp user",
  "errorCode": "130472"
}

The errorCode values are codes from the channel's platform (e.g. Meta for WhatsApp). Consult the specific channel's documentation for the meaning of each code.

The message stayed enqueued but was never delivered​

For WhatsApp and Messenger, enqueued is the normal initial status. Delivery confirmation arrives via webhook MessageStatus. If the user never received it:

  • Check if the number is active on WhatsApp
  • Check if the webhook is active — active: true in the response of GET /v1/organization/webhook/{id}
  • Check the webhook logs to see if there was any MessageStatus with status: failed

I tried to send free text on WhatsApp without a template and got an error​

WhatsApp only allows free text within an active session window (last 24h of user interaction). Outside that window, use an approved template.

Webhook issues​

My endpoint is not receiving events​

  1. Check that the URL is publicly accessible — try accessing the URL in a browser or with curl from another machine
  2. Check HTTPS — the endpoint must have a valid SSL certificate
  3. Check webhook logs — GET /v1/organization/webhook/{id}/webhook-log — see if there are failed attempts
  4. Check if the webhook is active — active: true in the response of GET /v1/organization/webhook/{id}

I'm receiving statusCode: 0 in the logs​

This means the Hub could not connect to your endpoint. Causes:

  • Server down or unreachable
  • Firewall blocking the connection
  • Invalid or expired SSL certificate
  • DNS not resolving the URL

My endpoint receives the webhook but returns 500​

A 500 error indicates a problem in your code's processing. Tips:

  • Add error handling around all endpoint code
  • Respond 200 OK immediately and process in the background
  • Log the full payload body to inspect what arrived

Pagination limits​

ParameterLimit
limit (pagination)Maximum 50 per page
Minimum offset0

For message sending limits per channel, consult the channel's own policies (WhatsApp Business API, Telegram Bot API, etc.).

Where to get help​

If none of the above solutions work, contact Hub Chatt2.me support providing:

  • The messageId or webhookLogId related to the issue
  • The exact payload you sent
  • The response received (status code + body)
  • The approximate time of the error