Operation
Errors and troubleshooting
Interpret error codes and choose the appropriate correction rather than repeating requests blindly.
Error response format#
Application errors include an HTTP status and an error object with code and message. Edge or network failures can return non-JSON responses; check Content-Type and HTTP status before parsing. Use the code for application decisions and display a safe message to operators.
{
"error": {
"code": "session_not_ready",
"message": "Connect your WhatsApp session before sending."
}
}HTTP status reference#
| Status | Interpretation |
|---|---|
| 400 | Invalid JSON or request fields, or an invalid webhook destination. Correct the input. |
| 401 | Missing, expired, revoked or unavailable API token. |
| 402 | No current trial or paid access for this operation. |
| 403 | Insufficient scope, account restriction, trial restriction, or session binding mismatch. |
| 404 | Resource not found within this account, or unsupported endpoint. |
| 405 | Use the documented HTTP method. Session stop/delete routes use POST. |
| 409 | Session not prepared/ready, idempotency conflict, or payment-state conflict. |
| 413 | The request exceeds the allowed body size. |
| 429 | Request rate or sending allowance exceeded. |
| 500 | The service could not complete the operation. Contact support if persistent. |
| 502 | The gateway/payment provider could not complete the request. |
| 503 | A required integration is not configured or available. |
Common error codes#
| Code | Next action |
|---|---|
| insufficient_scope | Use a key with the documented permission. |
| channel_scope | Use a key bound to this session or an account-wide key. |
| plan_required | Review trial expiry or subscription status. |
| trial_recipient | Use the linked number or request support approval for a test recipient. |
| message_limit | Check the account’s allowance and sending pace before retrying. |
| idempotency_required | Add a valid Idempotency-Key header. |
| idempotency_conflict | Reuse the original payload, or choose a new key for a genuinely new message. |
| session_not_ready / not_ready | Check the connection and authorize or restart it if needed. |
| preparing | Wait for provisioning before retrieving status/QR. |
| gateway_unavailable / gateway_error | Review connection status and contact support if persistent. |
Contact support#
Open a ticket from the workspace. Include the session ID, message ID if available, endpoint, HTTP status, error code, and approximate request time. Explain whether the issue is reproducible.
Never attach full API tokens, passwords, pairing QR codes, signing secrets, or private conversation content unless specifically needed and safely requested.