Errors

Format

Every failure answers with an HTTP status and a JSON body:

Error

{
  "error": "This recipient has opted out of messages",
  "code": "RECIPIENT_OPTED_OUT"
}

error is for people and may change; code is stable — branch on code. The text is English by default; send X-Lang: id (or ?lang=id, or Accept-Language: id) for Indonesian. Field names, enum values and codes are never translated. Some errors add fields, e.g. retry_after on 429.

HTTP status codes

Status	Meaning	What to do
`400`	The request is not valid (`VALIDATION_FAILED`, `INVALID_NUMBER`…)	Fix the request; do not retry as is.
`401`	Missing, wrong or revoked credential	Check the `Authorization` header.
`402`	Not included in your plan, or a plan limit is reached (`LIMIT_REACHED`)	Upgrade or free up the limit.
`403`	The credential may not do this (another business's device, a scoped key, an agent)	Use the right key or login.
`404`	The object does not exist (or is not yours)	Check the id.
`409`	Conflicts with the current state: device not connected, already done, recipient opted out in strict mode	Read `code`; often wait or change state first.
`413` / `415`	File too large / file type not supported	Send a smaller or supported file.
`422`	Understood but cannot be done with this input (for example nothing to summarize)	Change the input.
`429`	Rate limited (`RATE_LIMITED`)	Wait `Retry-After` seconds, then retry. See Rate limits.
`500`	Unexpected error on our side	Retry with backoff; contact support if it persists.
`502` / `503`	A service behind the API did not answer, or a feature is not set up on the platform (`NOT_CONFIGURED`)	Retry later.

Common error codes

Code	Meaning
`UNAUTHORIZED`	No valid credential.
`FORBIDDEN`	The credential is valid but not allowed here.
`KEY_SCOPE_FORBIDDEN`	A scoped child key tried to reach business-wide data or another device.
`KEY_MANAGEMENT_REQUIRES_LOGIN`	API keys are managed from a dashboard login.
`VALIDATION_FAILED`	A field is missing or wrong; `error` names it.
`NOT_FOUND`	No such object for your business.
`CONFLICT`	The state does not allow it (for example the device is not connected).
`NOT_CONNECTED`	The device is offline.
`INVALID_NUMBER` / `INVALID_JID` / `INVALID_TARGETS`	A phone number or chat id could not be read.
`RECIPIENT_OPTED_OUT`	The person asked not to be messaged (an error in strict mode, otherwise a warning).
`CONSENT_ATTESTATION_REQUIRED`	Start the broadcast with `"consent_attested": true`.
`CONFIRMATION_REQUIRED`	A destructive call needs an explicit confirmation field.
`LIMIT_REACHED`	A plan or platform limit is reached.
`RATE_LIMITED`	Too many requests; see `Retry-After`.
`NOT_CONFIGURED`	The feature is not available on the platform yet.
`NOT_SUPPORTED`	WhatsApp does not offer this operation for the device.
`UPSTREAM_ERROR`	A service behind the API (for example the AI model) failed; retry.
`WEBHOOK_URL_BLOCKED`	The webhook URL points at a private or local address.
`CURRENCY_NOT_SUPPORTED` / `COUPON_INVALID`	Billing input that cannot be used.

Each endpoint in the reference lists the statuses it can return.

Warnings on success

Some successful responses carry warnings: [{code, message}] — the request was done, but you may want to act (for example RECIPIENT_OPTED_OUT on POST /v1/sessions/{sessionId}/messages). Log them.