Troubleshooting
Fix common setup errors for API keys, senders, phone numbers, quotas, webhooks, OpenAPI, and SDK timeouts.
Start with the failed request
Record the HTTP status, response `error`, response `message`, endpoint, API-key role, and `message_id` if one was returned. Do not rotate keys or reconnect numbers before you know which layer failed.
Free Sandbox users should test `/api/otp/send` without `sender_id`. Paid connected-sender users should also test `GET /api/senders` and confirm their chosen sender is listed.
- No HTTP responseverify DNS, `https://api.hookmessage.com`, firewall access, and backend timeout.
- 401the `x-api-key` header is missing, revoked, mistyped, or still using an old rotated value.
- 403the key role does not match the endpoint, the workspace is inactive, or the key cannot use the requested sender.
- 422the JSON shape, receiver number, sender mode, routing rule, or plan feature is invalid.
- 429wait for `Retry-After`, then retry with the same idempotency key.
- 5xxkeep the safe response details, retry with backoff, and contact support if it continues.
Free Sandbox cannot send
Free Sandbox is a managed route. It does not need a connected customer number and an empty sender list is not itself an error.
- Remove `sender_id`managed Sandbox routing selects the company sender.
- Check the key roleuse `otp` for `/api/otp/send` and `send_message` for `/api/messages/send`.
- Check creditsopen Dashboard > Usage & Limits and confirm Sandbox credits remain.
- No active routing rulethe workspace or API key is not attached to a managed route; recreate the correct key or contact support.
- Receiver rejectedsend international digits such as `212612345678`, without `+`, spaces, or a local leading zero.
Connected sender cannot send
These checks apply only when a paid integration uses a customer-owned WhatsApp number.
- Sender missing from `GET /api/senders`assign it to this API key in Dashboard > API Keys.
- sender_not_connectedopen Dashboard > WhatsApp Numbers and scan a fresh QR.
- sender_disabledan operator paused the number; review its status before retrying.
- Wrong sender IDuse only an active ID returned to the same API key.
- Daily sender limitwait for reset or use an eligible sender according to your plan and routing policy.
Message stays queued or processing
HTTP 201 confirms acceptance, not delivery. Use the returned `message_id` to identify whether the delay is in the queue, worker, sender session, or WhatsApp delivery step.
- Check statuscall `GET /api/messages/{message_id}` and record `status`, `attempts`, and `error_message`.
- Check workspace healthopen Dashboard > Workspace Health for queue and sender warnings.
- Check senderpaid connected-sender mode requires `connected`; managed Sandbox routing does not expose a customer sender.
- Check worker and Redisif many messages remain processing, the delivery worker or queue dependency may be unavailable.
- Do not create duplicatesretry with the same `idempotency_key` until the original outcome is known.
Webhooks and SDKs
After direct cURL succeeds, compare the SDK request with the working cURL request. The endpoint, role, headers, sender mode, and receiver format must remain the same.
- Webhook signature invalidverify the exact raw request bytes with the current signing secret and timestamp header.
- No webhook deliveryconfirm public HTTPS reachability, active endpoint status, and matching event subscriptions.
- SDK timeoutverify `HOOKMESSAGE_BASE_URL=https://api.hookmessage.com` and choose a timeout that fits your server runtime.
- OpenAPIdownload `https://api.hookmessage.com/openapi.yaml`; generated clients still require server-only secret injection.
- Support payloadsend the endpoint, UTC time, HTTP status, error code, workspace ID, API-client name, and message ID. Never send the plaintext API key.
Need help?
Use Book Integration Help if you want setup help for OTP or automated customer messaging.
Continue building
Next steps
Errors and limits
Use status codes and message status records to decide whether to retry, fix input, reconnect a sender, or upgrade limits.
Message queue
Sending is asynchronous: the API queues work, workers deliver it, and status changes later.
Message status and history
Use message IDs to trace status, delivery attempts, timestamps, and failure reasons.
Production readiness checklist
Use this checklist before switching a workspace to production traffic.