wa-server Docs — Errors & Troubleshooting

Error Format

{
  "error": {
    "code": "invalid_api_key",
    "message": "Bearer token is missing or invalid",
    "details": {
      "field": "jid"
    }
  },
  "request_id": "..."
}

code: short machine-friendly identifier.
message: human-friendly description.
details: optional object (for example validation_error includes details.field).
request_id: use for log correlation and support.

Common Scenarios

HTTP	Code	What it means	How to fix
400	`validation_error`	Payload failed validation (missing field, bad UUID, invalid JSON, mime not allowed, etc.).	Fix the indicated field; see `details.field` when present.
401	`invalid_api_key`	Missing/invalid `Authorization: Bearer ...` header.	Send the Bearer token header for all device/message endpoints.
401	`unauthorized`	Bearer token missing/invalid for `/apps` endpoints.	Send a valid JWT (internal) with `Authorization: Bearer <token>`.
403	`forbidden`	Access denied for the requested resource.	Confirm the app/tenant/device ownership.
403	`group_posting_restricted`	WhatsApp group/community settings prevent this device from posting.	Do not auto-retry. Check whether the chat is admin-only or comments are disabled.
404	`not_found`	Resource does not exist for the tenant/app.	Re-check IDs via list endpoints before calling the action.
409	`conflict`	Resource already exists (e.g., duplicate app/device name per tenant).	Use a unique name/code or delete the old entry first.
409	`device_not_connected`	Send attempted while device is offline.	Regenerate QR (`/qr`), scan, and retry after connection is up.
409	`qr_reset_not_allowed`	QR regeneration requested while a QR/session is still active.	Disconnect first, or wait until the current QR expires.
409	`too_many_devices`	WhatsApp rejected pairing because too many devices are linked.	Unlink an existing device in WhatsApp, then regenerate QR.
409	`client_outdated`	WhatsApp provider requires client update.	Reconnect the device to update the client version.
408	`request_canceled`	Request was canceled before completion.	Retry the request if needed.
409	`logged_out`	Session was logged out remotely.	Regenerate a new QR and relink.
410	`device_destroyed`	Action attempted on a destroyed device.	Create a new device and link it with a fresh QR.
429	`provider_rate_limit`	WhatsApp provider rate limit encountered. This is temporary and the system will automatically retry your request.	No action needed; the system automatically retries with backoff.
500	`internal_error`	Unexpected server error.	Retry with `request_id` and contact support if persistent.
502	`provider_error`	Provider/upstream service error.	Retry after a short delay; check provider status.
503	`whatsapp_connection_aborted`	WhatsApp connection was aborted during request.	Retry the request. If persistent, disconnect and relink device.
503	`whatsapp_connection_lost`	WhatsApp connection dropped during request.	Retry the request. If persistent, reconnect or relink device.
504	`group_prekey_timeout`	Timeout while preparing encryption/prekeys for a large WhatsApp group.	Retry with backoff. This is usually temporary and should be treated as retryable.
504	`upstream_timeout`	Timeout while waiting for WhatsApp provider.	Retry the request; for large groups this may indicate slow encryption/prekey setup rather than a permanent failure.

Troubleshooting Checklist

Verify Bearer token header and base URL https://wa.sagad.net.
Check device status via GET /devices; if disconnected, regenerate QR.
For large groups/community chats, use a longer client timeout and treat group_prekey_timeout / upstream_timeout as retryable.
Ensure media payload uses correct mime type and base64/URL is reachable.
Check webhook receiver logs (idempotent handling) to confirm downstream delivery.
Use request_id to trace logs when escalating issues.