Errors & Rate Limits — Washeej API v1

Error codes

Code	HTTP	Description
`unauthorized`	401	Missing or invalid credentials.
`invalid_credentials`	401	client-id / client-secret do not match.
`invalid_token`	401	OAuth bearer token expired or revoked.
`ip_not_whitelisted`	401	Caller IP is not on the account whitelist (API key auth).
`insufficient_scope`	403	Token or key lacks the required scope.
`subscription_required`	403	Active plan with API access is required.
`billing_blocked`	403	WhatsApp Cloud billing is not eligible for this number.
`rate_limit_exceeded`	429	More than 120 requests per minute for this account.
`not_found`	404	Resource not found or not owned by the account.
`validation_error`	422	Request parameters failed validation.
`duplicate_contact`	409	Contact with this phone already exists.
`marketing_suppressed`	422	Contact opted out of marketing messages.
`capability_error`	422	Operation not supported on this channel type.
`feature_disabled`	403	The channel type (Cloud / Device QR / Coexistence) is not available in the account plan or platform config.
`limit_reached`	403	The plan's WhatsApp account quota (account_limit) is exhausted.
`duplicate_device`	409	This phone number is already connected as a device channel.
`invalid_channel_type`	422	Operation only applies to Device (QR) channels.
`unsupported_type`	422	POST /devices only creates type=device. Cloud numbers use hosted onboarding sessions.
`return_url_not_allowed`	422	return_url host is not among the redirect URIs registered on your developer app.
`gowa_error`	502	The WhatsApp device service failed to process the request. Retry later.
`qr_failed`	422	QR code generation failed for this device.
`pairing_failed`	422	Pairing code generation failed — try the QR code instead.
`invalid_phone`	422	Phone number could not be normalized or is invalid.
`user_error`	401	Credentials did not resolve to an API user.
`send_failed`	422	Upstream WhatsApp send failed; inspect message details / Meta error.
`exception`	500	Unexpected server exception while processing the request.

Rate limiting

Default: 120 requests / minute / account. Back off exponentially when you receive 429 / rate_limit_exceeded.

Billing gate

Cloud API payment eligibility Outbound Cloud sending may return billing_blocked when Meta payment eligibility for the WhatsApp number is not satisfied. Resolve billing in Meta Business Manager, then retry.

Marketing opt-out

marketing_suppressed MARKETING template sends may return marketing_suppressed when the contact opted out for that WhatsApp number. Do not retry the same MARKETING template until the contact opts back in; use UTILITY / AUTHENTICATION for transactional traffic instead.

Pagination

List endpoints return a pagination object with current_page, last_page, and total. Pass page and per_page (max 100 where documented).