Troubleshooting

Authentication and scope

For 401, check that x-api-key is present, correctly copied, valid and unrevoked/unexpired. Also check application/access availability in the dashboard; replace an expired key or contact support if availability cannot be restored. Keep keys on your backend.

For 404, verify the UUID and application's scope. A valid key belonging to another application receives resource 404; it is not an invalid-key 401. List your webhooks/channels using the appropriate application key, and ensure referenced channel, webhook and log IDs belong together.

Invalid request (400)

Read statusCode, code, message, hint and optional errors[{field,code,details}]. Check required fields, types, recipient format, channel content support, and invalid field combinations against that endpoint's schema. See the common HTTP error format. Do not substitute send-result errorCode for the HTTP error's code.

Operation-specific responses can also include 402 (funds), 409 (concurrent change/retry), 429 (rate limit) and 503 (temporary unavailability). Follow the affected operation's reference; retries must respect its idempotency and concurrency rules.

Message delivery

A send result can contain provider error fields:

{
  "messageId": null,
  "status": "error",
  "errorMessage": "Provider could not deliver the message",
  "errorCode": "131026"
}

A successful HTTP response or initial enqueued send status is not proof of recipient delivery. Check subscribed message_status events and correlate messageId / providerMessageId. The normalized failure state is error, while WhatsApp's subscription is failed. Subscribe to the exact provider status names and verify an enabled channel binding.

Free text on WhatsApp requires the applicable active customer window; outside it use an approved template. Check recipient/channel availability and provider error details before retrying a send.

WhatsApp provider authentication

Your Application API key authenticates calls to the Hub. The Hub separately manages the WhatsApp provider connection and, on universal-token connections, the provider tokens and their renewal. If a send passes Hub authentication but returns a provider submission failure, generating a new Hub API key does not repair that connection.

Check the channel's availability and Meta authorization in the dashboard, then contact support if the failure persists. Include safe channel/message/log IDs, the time and timezone, and the error fields returned by the operation. Do not send Hub API keys, provider tokens or authorization headers. See connection and renewal.

Renewal does not automatically replay a failed message. When a timeout leaves the earlier submission outcome uncertain, check available status events and message records before deciding whether to submit again; an immediate retry can send the same message twice. Follow the affected operation's error and retry contract.

No webhook events

1. Verify the receiver URL is reachable over HTTPS with valid DNS/TLS and accepts POST on the registered path.
2. Check webhook active: true and isVerified: true with GET /v1/organization/webhook/WEBHOOK_UUID.
3. Read GET /v1/communication/channel/CHANNEL_UUID/webhook/WEBHOOK_UUID/config. It must have enabled: true and the matching provider subscriptions. Creating a webhook does not create this binding.
4. Check logs, then fix authentication/token echo and revalidate if inactive.
5. For Agent forwarding, check the configured transfer mode: summary_on_transfer can suppress active-session message/status forwarding; operational closure events have their own subscription.

statusCode: null in logs

No HTTP response was recorded. Check DNS, TLS, connectivity/firewalls and receiver timeout. A timeout can occur after connection, including while your server waits for storage. Event timeout is 30 seconds, validation timeout 10 seconds. statusCode is nullable, not 0; request/response bodies are stored strings or null.

Receiver returns 500 or loses accepted work

Authenticate, validate, persist or enqueue durably, then return any 2xx promptly. Process the accepted work with your worker and its own retries. An in-memory queue or processing after an unrecorded early acknowledgement can lose events. Hub cannot retry a successful log to recover your later processing failure. The combined receiver shows safe acceptance; inspect retry eligibility for failed Hub attempts.

Pagination and response parsing

Endpoint	Pagination
Webhook logs	Page index offset (minimum 0), limit 1–50
Wallet parent groups	Page index offset (minimum 0), limit 1–200
Wallet session items	Opaque cursor, limit 1–50; omit cursor on the first page

Other endpoints define their own limits; there is no universal maximum of 50. A 200 empty list is a valid scoped/filter result. JSON is the default, but do not parse a 204 empty DELETE response or a Public Calendar avatar image redirect as JSON.

Support

Provide relevant message/log/resource IDs, HTTP status and safe response fields, the approximate time/timezone, and a redacted request example. Remove API keys, signing secrets, authorization headers and personal information that is not needed for diagnosis.