Start with the failing layer
Capture the endpoint, HTTP status, safe error code, source reference, and message ID. Avoid changing credentials or sender sessions until you know whether the failure is authentication, authorization, validation, queue processing, or WhatsApp delivery.
- No HTTP response: inspect DNS, TLS, timeout, and network access.
- 401: the API key is missing, malformed, revoked, or loaded from the wrong environment.
- 403: the authenticated key lacks the required role or resource access.
- 422: the request is understood but contains an invalid or unavailable value.
- 429: the request exceeded a rate or usage boundary.
- 201 queued then failed: inspect the message status and sender health.
Check authentication and role
Use `x-api-key` from a server process. An OTP key calls `/api/otp/send`; a send-message key calls `/api/messages/send`. Do not reuse customer session cookies as API credentials.
- Confirm the key exists in the deployed environment.
- Check for whitespace or a stale rotated value.
- Confirm the key is active and assigned to the intended workspace.
- Never paste the plaintext key into support tickets or client logs.
Check sender and plan mode
Free Sandbox uses a managed HookMessage sender and must omit `sender_id`. Paid sender mode requires an active sender that belongs to the same workspace and is assigned to the API key when assignment is enabled.
- Do not copy a sender ID into a Free Sandbox request.
- Confirm the connected number is active rather than archived or disconnected.
- Confirm the plan permits the number and current usage.
- If automatic routing is configured, omit the sender ID and let the route choose.
Check queue and delivery
A queued message has passed request validation. Use its message ID to inspect processing attempts and the final error. If many messages stall together, check worker, Redis, sender session, and platform health rather than retrying every message.
curl "$HOOKMESSAGE_BASE_URL/api/messages/$MESSAGE_ID" \
-H "x-api-key: $HOOKMESSAGE_API_KEY"Build a useful support report
A safe support report shortens diagnosis without leaking secrets. Include timestamp, endpoint, HTTP status, error code, message ID, sender ID, and source reference. Redact API keys, OTP values, message bodies, and recipient numbers.