Errors

One error envelope for every v2 error, with a stable code, the HTTP status, what it means and what to do — plus the full catalog.

Every error has the same shape. Branch on error.code (stable), not on the message (it may be reworded).

422 Unprocessable Entity

{
  "error": {
    "code": "SAFETY_SUPPRESSED",
    "message": "The recipient opted out of messages from this number.",
    "details": {
      "to": "2010****4567"
    },
    "docsUrl": "https://mursilat.com/developers/v2/errors#SAFETY_SUPPRESSED",
    "requestId": "req_6604bedc8c489f20e582691a"
  }
}

Field	Meaning
`code`	MeaningStable machine code. Every code is listed below with its own link.
`message`	MeaningHuman-readable English explanation (may change).
`details`	MeaningOptional extra data: the field at fault, `retryAt`, limits…
`docsUrl`	MeaningA link straight to the code in this catalog.
`requestId`	MeaningAlso in the `X-Request-Id` header. Quote it to support.

5xx answers never carry internals (INTERNAL_ERROR). Codes marked retryable can succeed later unchanged — honour Retry-After / details.retryAt; the others need a change on your side.

Error catalog

Filter errors

174 codes

Code	Status	Meaning	What to do
`ACCOUNT_KEY_REQUIRED`Authentication	Status401fix the request	MeaningThis endpoint needs an account key, not a number key.	What to doUse Authorization: Bearer wsl_live_… (number keys only send messages from their number).
`API_KEY_EXPIRED`Authentication	Status401fix the request	MeaningThe key expired.	What to doCreate a new key (or rotate before expiry).
`API_KEY_INVALID`Authentication	Status401fix the request	MeaningThe API key is not valid.	What to doCopy the key again from Settings → API keys (it is shown only once; create a new one if lost).
`API_KEY_REQUIRED`Authentication	Status401fix the request	MeaningNo API key was sent.	What to doSend Authorization: Bearer wsl_live_…
`API_KEY_REVOKED`Authentication	Status401fix the request	MeaningThe key was revoked.	What to doUse another key or create a new one.
`IMPERSONATION_ACTION_FORBIDDEN`Authentication	Status403fix the request	MeaningNot allowed during a support session.	What to doThe account owner must do it.
`IP_NOT_ALLOWED`Authentication	Status403fix the request	MeaningThe key is limited to other IP addresses.	What to doCall from an allowed IP or edit the key allowlist.
`KEY_NUMBER_RESTRICTED`Authentication	Status403fix the request	MeaningNumber-restricted keys cannot do account-wide actions.	What to doUse a key with access to all numbers.
`NUMBER_NOT_ALLOWED`Authentication	Status403fix the request	MeaningThe key is restricted to other numbers.	What to doUse a key that includes this number.
`SCOPE_REQUIRED`Authentication	Status403fix the request	MeaningThe key lacks the scope of this endpoint.	What to doAdd the scope in details.required to the key.
`USER_SUSPENDED`Authentication	Status403fix the request	MeaningThe account is suspended.	What to doContact support.
`API_KEY_NOT_FOUND`Authentication	Status404fix the request	MeaningKey not found.	What to doCheck the id.
`API_KEY_LIMIT_REACHED`Authentication	Status409fix the request	MeaningToo many active keys (20).	What to doRevoke an unused key.
`API_TEMPORARY_BAN`Authentication	Status429retryable	MeaningSending through the API is paused for this number after abuse-level traffic.	What to doSlow down and retry after retryAfterSeconds.
`AUTH_TOO_MANY_FAILURES`Authentication	Status429retryable	MeaningToo many failed authentications from your IP.	What to doFix the key and wait Retry-After seconds.
`RATE_LIMITED`Authentication	Status429retryable	MeaningRate limit of this key reached.	What to doWait Retry-After seconds; watch X-RateLimit-Remaining.
`API_KEY_EXPIRY_INVALID`Request	Status400fix the request	MeaningexpiresInDays must be 1–730.	What to doFix the value.
`API_KEY_GRACE_INVALID`Request	Status400fix the request	MeaninggraceMinutes must be 0–1440.	What to doFix the value.
`API_KEY_IP_ALLOWLIST_INVALID`Request	Status400fix the request	MeaningInvalid IP / CIDR in the allowlist.	What to doUse IPv4/IPv6 addresses or CIDR ranges.
`API_KEY_NAME_INVALID`Request	Status400fix the request	MeaningKey name is required (1–80).	What to doSend a name.
`API_KEY_NUMBERS_INVALID`Request	Status400fix the request	Meaningnumbers must be "ALL" or your number ids.	What to doChoose ALL or valid number ids.
`API_KEY_SCOPES_INVALID`Request	Status400fix the request	MeaningUnknown or missing scopes.	What to doPick scopes from the list.
`CONFIRMATION_REQUIRED`Request	Status400fix the request	MeaningA destructive action needs an explicit confirm parameter.	What to doAdd the confirm parameter described in the docs.
`IDEMPOTENCY_KEY_INVALID`Request	Status400fix the request	MeaningIdempotency-Key must be 1–191 visible ASCII characters.	What to doUse e.g. order-1042-confirm.
`IDEMPOTENCY_KEY_REQUIRED`Request	Status400fix the request	MeaningIdempotency-Key header is required.	What to doSend one unique value per logical request.
`PAGINATION_CURSOR_INVALID`Request	Status400fix the request	Meaningcursor is invalid.	What to doPass nextCursor unchanged.
`PAGINATION_LIMIT_INVALID`Request	Status400fix the request	Meaninglimit is out of range.	What to doUse 1–100.
`VALIDATION_FAILED`Request	Status400fix the request	MeaningThe request is invalid.	What to doSee details.errors / details.field.
`ROUTE_NOT_FOUND`Request	Status404fix the request	MeaningNo such endpoint.	What to doCheck method and path (/api/v2/…).
`IDEMPOTENCY_IN_PROGRESS`Request	Status409retryable	MeaningThe first request with this key is still running.	What to doRetry in a few seconds.
`IDEMPOTENCY_KEY_REUSED`Request	Status409fix the request	MeaningThis Idempotency-Key was used with a different request.	What to doUse a new key for a new request.
`UNSUPPORTED_CONTENT_TYPE`Request	Status415fix the request	MeaningBody must be JSON (or multipart for uploads).	What to doSet Content-Type: application/json.
`API_ACCESS_NOT_IN_PLAN`Plan	Status403fix the request	MeaningYour plan does not include API access.	What to doUpgrade to a plan with API.
`AUTO_REPLIES_NOT_IN_PLAN`Plan	Status403fix the request	MeaningYour plan does not include auto-replies.	What to doUpgrade.
`FEATURE_NOT_IN_PLAN`Plan	Status403fix the request	MeaningYour plan does not include this feature.	What to doUpgrade (details.feature).
`GROUPS_NOT_IN_PLAN`Plan	Status403fix the request	MeaningYour plan does not include groups.	What to doUpgrade.
`MESSAGES_QUOTA_EXCEEDED`Plan	Status403fix the request	MeaningNo messages left in your plan.	What to doBuy a message pack or upgrade.
`NO_ACTIVE_PLAN`Plan	Status403fix the request	MeaningNo active plan.	What to doSubscribe.
`PLAN_NUMBERS_LIMIT_REACHED`Plan	Status403fix the request	MeaningYour plan’s number limit is reached.	What to doUpgrade or delete a number.
`WEBHOOKS_NOT_IN_PLAN`Plan	Status403fix the request	MeaningYour plan does not include webhooks.	What to doUpgrade.
`NUMBER_ID_REQUIRED`Numbers	Status400fix the request	MeaningnumberId is required with an account key.	What to doSend numberId.
`SESSION_NOT_CONNECTED`Numbers	Status400retryable	MeaningThe number is not connected.	What to doReconnect (scan the QR again) and retry.
`NUMBER_NOT_FOUND`Numbers	Status404fix the request	MeaningNumber not found in this account.	What to doCheck numberId (GET /v2/numbers).
`NUMBER_ALREADY_CONNECTED`Numbers	Status409fix the request	MeaningThe number is already connected.	What to doNothing to pair.
`NUMBER_BANNED`Numbers	Status409fix the request	MeaningWhatsApp restricted this number.	What to doContact support; do not reconnect repeatedly.
`NUMBER_NOT_CONNECTED`Numbers	Status409retryable	MeaningThe number is not connected.	What to doReconnect it first.
`NUMBER_NOT_PAIRING`Numbers	Status409fix the request	MeaningThe number is not waiting for pairing.	What to doCall POST /reconnect first.
`PAIRING_CODE_UNAVAILABLE`Numbers	Status409fix the request	MeaningA pairing code is not available; use the QR.	What to doFetch GET /qr.
`SESSION_OWNED_BY_OTHER_INSTANCE`Numbers	Status409retryable	MeaningThe number is running on another server instance.	What to doRetry in a minute.
`CONTACT_CHECK_TOO_MANY`Numbers	Status422fix the request	MeaningUp to 50 numbers per check.	What to doSplit the list; for big lists create a campaign (it checks safely).
`PAIRING_CODE_FAILED`Numbers	Status502retryable	MeaningWhatsApp did not return a pairing code.	What to doRetry or use the QR.
`INTERACTIVE_INVALID`Messages	Status400fix the request	MeaningInvalid buttons / list / link button (INTERACTIVE_* codes).	What to doSee details.field and the interactive limits.
`INTERACTIVE_RESERVED_TITLE`Messages	Status400fix the request	MeaningAn option title is an opt-out keyword.	What to doRename it (e.g. "إلغاء الطلب").
`INVALID_RECIPIENT`Messages	Status400fix the request	MeaningInvalid phone number.	What to doDigits with country code, e.g. 201001234567.
`MESSAGE_CONTACT_INVALID`Messages	Status400fix the request	MeaningInvalid contact card.	What to doSee details.reason / index.
`MESSAGE_EVENT_INVALID`Messages	Status400fix the request	MeaningInvalid event dates.	What to doSee details.reason.
`MESSAGE_FIELD_INVALID`Messages	Status400fix the request	MeaningA field has the wrong shape.	What to doSee details.field / details.reason.
`MESSAGE_FIELD_REQUIRED`Messages	Status400fix the request	MeaningA required field is missing.	What to doSee details.field.
`MESSAGE_LOCATION_INVALID`Messages	Status400fix the request	MeaningLatitude / longitude out of range.	What to dolat −90..90, lng −180..180.
`MESSAGE_MEDIA_REQUIRED`Messages	Status400fix the request	MeaningA file / media is required.	What to doSend media.url, media.id or a multipart file.
`MESSAGE_MENTIONS_GROUP_ONLY`Messages	Status400fix the request	MeaningMentions work in groups only.	What to doRemove mentions.
`MESSAGE_POLL_INVALID`Messages	Status400fix the request	MeaningInvalid poll.	What to doSee details.reason.
`MESSAGE_REACTION_INVALID`Messages	Status400fix the request	Meaningemoji must be one emoji (or "").	What to doSend one emoji.
`MESSAGE_TEXT_TOO_LONG`Messages	Status400fix the request	MeaningText over its limit.	What to doSee details.limit.
`MESSAGE_TYPE_NOT_SUPPORTED`Messages	Status400fix the request	MeaningThis type cannot be sent from a linked device.	What to dodetails.reason explains; use the suggested alternative.
`MESSAGE_TYPE_REQUIRED`Messages	Status400fix the request	Meaningtype is required.	What to doSee the message types.
`MESSAGE_UNEXPECTED_FIELD`Messages	Status400fix the request	MeaningA field of another message type.	What to doRemove details.field.
`MESSAGE_VIDEO_NOTE_TOO_LONG`Messages	Status400fix the request	MeaningVideo notes are ≤60 s.	What to doTrim the video.
`SCHEDULE_AT_INVALID`Messages	Status400fix the request	MeaningscheduleAt must be 1 minute – 30 days ahead (ISO 8601).	What to doSend an ISO time like 2026-11-01T09:00:00+02:00.
`MESSAGE_MEDIA_NOT_FOUND`Messages	Status404fix the request	MeaningUnknown media id (or another number’s).	What to doUpload again on the same number.
`MESSAGE_NOT_FOUND`Messages	Status404fix the request	MeaningMessage not found.	What to doUse the id returned by POST /v2/messages (kept 30 days).
`MESSAGE_REPLY_TARGET_NOT_FOUND`Messages	Status404fix the request	MeaningreplyTo is not a message of this chat.	What to doUse a message id of this chat.
`MESSAGE_DELETE_WINDOW_PASSED`Messages	Status409fix the request	MeaningDelete for everyone is possible for 48 h.	What to doDelete for me instead.
`MESSAGE_EDIT_WINDOW_PASSED`Messages	Status409fix the request	MeaningEdits are possible for 15 minutes.	What to doSend a new message.
`MESSAGE_NOT_CANCELLABLE`Messages	Status409fix the request	MeaningThe scheduled message is already being sent.	What to doDelete it after it is sent.
`MESSAGE_NOT_DELETABLE`Messages	Status409fix the request	MeaningThis message cannot be deleted for everyone.	What to doDelete for me (forEveryone=false).
`MESSAGE_NOT_EDITABLE`Messages	Status409fix the request	MeaningThis message cannot be edited / reacted to.	What to doOnly your own sent text messages.
`MESSAGE_NOT_SENT_YET`Messages	Status409fix the request	MeaningThe message is scheduled and not sent yet.	What to doCancel it with DELETE instead.
`SCHEDULE_LIMIT_REACHED`Messages	Status409fix the request	MeaningToo many scheduled messages are waiting (1 000 per account).	What to doCancel some or send now.
`MESSAGE_MEDIA_EXPIRED`Messages	Status410fix the request	MeaningThe upload expired (24 h).	What to doUpload again.
`MESSAGE_MEDIA_TOO_LARGE`Messages	Status413fix the request	MeaningFile over the type limit.	What to doSee details.limitBytes.
`MESSAGE_MEDIA_TYPE_NOT_ALLOWED`Messages	Status415fix the request	MeaningThe bytes do not match the type.	What to doSend the right file or type.
`MESSAGE_MEDIA_FETCH_FAILED`Messages	Status422retryable	Meaningmedia.url could not be fetched safely.	What to doUse a public https URL that answers within 20 s.
`MESSAGE_STICKER_INVALID`Messages	Status422fix the request	MeaningThe image cannot become a sticker.	What to doUse a smaller PNG/WebP.
`SCHEDULE_MEDIA_URL_ONLY`Messages	Status422fix the request	MeaningScheduled media must use media.url.	What to doUse a public https URL; uploads are kept only until sent.
`SCHEDULING_DISABLED`Messages	Status422fix the request	MeaningScheduled messages are not enabled (available on request).	What to doSend now without scheduleAt, or ask support to enable scheduling.
`LIMITS_INVALID`Number Shield	Status400fix the request	MeaningInvalid limits.	What to doIntegers within bounds; maxPerHour ≤ maxPerDay.
`STATS_RANGE_INVALID`Number Shield	Status400fix the request	MeaningInvalid date range.	What to doYYYY-MM-DD, ≤ 92 days.
`ACCOUNT_NUMBER_ROTATION`Number Shield	Status403fix the request	MeaningA new number was linked right after a ban: messages to new contacts wait for a review.	What to doContact support; an administrator reviews the account.
`ACCOUNT_RESTRICTED`Number Shield	Status403fix the request	MeaningThe account is restricted: only replies to people who wrote in the last 24h are allowed.	What to doContact support; an administrator reviews and lifts the restriction.
`SAFETY_NUMBER_BANNED`Number Shield	Status403fix the request	MeaningWhatsApp restricted the number.	What to doContact support.
`NUMBER_NOT_CONNECTED_YET`Number Shield	Status409fix the request	MeaningConnect the number once first.	What to doPair it.
`NUMBER_PAUSE_NOT_YOURS`Number Shield	Status409retryable	MeaningThis pause protects the number and cannot be lifted from the API.	What to doIt ends on its own at details.until.
`SESSION_PHONE_UNKNOWN`Number Shield	Status409retryable	MeaningThe number’s phone is not known yet.	What to doReconnect and retry.
`SAFETY_CONTENT_BLOCKED`Number Shield	Status422fix the request	MeaningContent blocked to protect the number (reasons[]).	What to doRemove shorteners / links for young numbers / vary identical texts; reason CONTENT_PROHIBITED (+ category) = prohibited content to new contacts.
`SAFETY_SUPPRESSED`Number Shield	Status422fix the request	MeaningThe recipient opted out.	What to doDo not message them.
`SAFETY_NUMBER_PAUSED`Number Shield	Status423retryable	MeaningThe number is paused (by you or by the Number Shield).	What to doRetry at retryAt; replies to recent chats still work.
`ACCOUNT_COD_CAP_REACHED`Number Shield	Status429retryable	MeaningThe account's daily cap of cash-on-delivery order messages is used up.	What to doRetry at retryAt (next local midnight); the cap grows with the account level.
`ACCOUNT_DAILY_CAP_REACHED`Number Shield	Status429retryable	MeaningThe account's daily budget of messages to new contacts (all numbers together) is used up.	What to doRetry at retryAt (next local midnight); the budget grows with the account level.
`SAFETY_DAILY_CAP_REACHED`Number Shield	Status429retryable	MeaningDaily limit of the number reached (warm-up or your limit).	What to doRetry at retryAt (next local midnight).
`SAFETY_HOURLY_CAP_REACHED`Number Shield	Status429retryable	MeaningHourly limit reached.	What to doRetry at retryAt.
`SAFETY_NUMBER_BUSY`Number Shield	Status429retryable	MeaningAnother send of the number is in flight.	What to doRetry shortly.
`SAFETY_PACING`Number Shield	Status429retryable	MeaningMessages to new contacts are spaced out.	What to doRetry at retryAt; better: let campaigns pace for you.
`SAFETY_QUIET_HOURS`Number Shield	Status429retryable	MeaningCampaigns wait during quiet hours.	What to doRetry at retryAt.
`CAMPAIGN_CONTENT_INVALID`Campaigns	Status400fix the request	MeaningInvalid campaign content.	What to doSee details.field.
`CAMPAIGN_NOT_CANCELLABLE`Campaigns	Status400fix the request	MeaningThis campaign cannot be cancelled.	What to doIt already ended.
`CAMPAIGN_RECIPIENTS_REQUIRED`Campaigns	Status400fix the request	MeaningGive recipients, contactListId or audience (exactly one).	What to doPick one source.
`URL_SHORTENER`Campaigns	Status400fix the request	MeaningLink shorteners are blocked.	What to doUse the full link.
`AUP_NOT_ACCEPTED`Campaigns	Status403fix the request	MeaningThe account owner has not accepted the acceptable use policy yet.	What to doSign in to the dashboard once and accept the policy.
`CAMPAIGN_NOT_FOUND`Campaigns	Status404fix the request	MeaningCampaign not found.	What to doCheck the id.
`CAMPAIGN_ACTIVE`Campaigns	Status409fix the request	MeaningRunning campaigns cannot be deleted.	What to doCancel it first.
`CAMPAIGN_NOT_DRAFT`Campaigns	Status409fix the request	MeaningOnly drafts can be started.	What to doCheck the status.
`CAMPAIGN_RESUME_BLOCKED`Campaigns	Status409fix the request	MeaningThe platform paused this campaign; you cannot resume it.	What to doSee details.pauseReason; time-boxed pauses resume after pausedUntil.
`CAMPAIGN_STATE_CHANGED`Campaigns	Status409retryable	MeaningThe campaign changed meanwhile.	What to doRead it again and retry.
`CAMPAIGN_PURGED`Campaigns	Status410fix the request	MeaningRecipients were deleted after the campaign ended (privacy).	What to doOnly totals remain; export during the keep window next time.
`CAMPAIGN_NO_RECIPIENTS`Campaigns	Status422fix the request	MeaningNo valid recipients.	What to doCheck the phone numbers.
`CAMPAIGN_OPT_IN_REQUIRED`Campaigns	Status422fix the request	MeaningConfirm that recipients agreed to receive your messages.	What to doSend optInConfirmed: true (only for real opt-ins).
`CAMPAIGN_TOO_MANY_RECIPIENTS`Campaigns	Status422fix the request	MeaningAt most 10 000 inline recipients.	What to doUse a contact list.
`CONTENT_PROHIBITED`Campaigns	Status422fix the request	MeaningThe campaign contains prohibited content (details.category); the account receives a strike.	What to doRemove the prohibited topic (loans, betting, crypto signals, adult, political, weapons/drugs, WhatsApp links, impersonation).
`LIST_QUALITY_LOW`Campaigns	Status422fix the request	MeaningThe recipient list looks low quality (details.reason: NOT_ON_WHATSAPP / SEQUENTIAL_NUMBERS / NEVER_SEEN_BOUGHT_LIST).	What to doSend only to people who agreed to hear from you; remove invalid / generated numbers.
`AUTO_REPLY_DELAY_INVALID`Auto-replies	Status400fix the request	MeaningdelaySeconds needs 0 ≤ min ≤ max ≤ 120.	What to doFix the values.
`AUTO_REPLY_KEYWORDS_REQUIRED`Auto-replies	Status400fix the request	MeaningKeyword rules need keywords.	What to doAdd trigger.keywords.
`AUTO_REPLY_PATTERNS_REQUIRED`Auto-replies	Status400fix the request	MeaningRegular-expression rules need at least one pattern.	What to doAdd trigger.patterns (1–10 patterns).
`AUTO_REPLY_REGEX_INVALID`Auto-replies	Status400fix the request	MeaningA pattern is not a valid RE2 regular expression, uses a feature RE2 does not support (lookarounds, backreferences, atomic / possessive), contains non-ASCII digits, tashkeel / tatweel or invisible characters, exceeds the limits (200 chars, {n} ≤ 100, complexity) or matches an empty message.	What to dodetails: patternIndex, reason, position (1-based) and messages {en, ar}. Fix that pattern; test it with POST /auto-replies/test.
`AUTO_REPLY_REGEX_RULE_LIMIT`Auto-replies	Status400fix the request	MeaningAn account can have at most 50 regular-expression rules.	What to doDelete or merge REGEX rules (details.limit, details.used).
`AUTO_REPLY_REGEX_TOO_MANY_PATTERNS`Auto-replies	Status400fix the request	MeaningA rule can have at most 10 patterns.	What to doCombine alternatives with \| or split the rule.
`AUTO_REPLY_SCHEDULE_REQUIRED`Auto-replies	Status400fix the request	MeaningAway rules need business hours.	What to doAdd schedule.
`INVALID_SCHEDULE`Auto-replies	Status400fix the request	MeaningInvalid schedule or time zone.	What to doUse HH:mm and an IANA time zone.
`AUTO_REPLY_ACCOUNT_WIDE_READ_ONLY`Auto-replies	Status403fix the request	MeaningRules for all numbers are read-only for keys restricted to some numbers.	What to doUse a key with access to all numbers.
`AUTO_REPLY_NOT_FOUND`Auto-replies	Status404fix the request	MeaningRule not found on this number.	What to doCheck ids.
`AUTO_REPLY_REGEX_ENGINE_UNAVAILABLE`Auto-replies	Status503retryable	MeaningRegular expressions are temporarily unavailable.	What to doRetry later; literal keyword rules keep working.
`OTP_INPUT_INVALID`OTP	Status400fix the request	MeaningInvalid OTP request.	What to doSee details.field.
`OTP_NOT_FOUND`OTP	Status404fix the request	MeaningOTP not found.	What to doUse the otpId from POST /v2/otp (kept 7 days).
`OTP_ACCOUNT_RATE_LIMITED`OTP	Status429retryable	MeaningToo many different OTP recipients for your account this hour.	What to doWait; OTPs are for people who just asked for one.
`OTP_RECIPIENT_RATE_LIMITED`OTP	Status429retryable	MeaningToo many codes to this recipient (5 per hour).	What to doLet the user wait; never loop sends.
`OTP_VERIFY_RATE_LIMITED`OTP	Status429retryable	MeaningToo many verification calls from this key.	What to doSlow down.
`GROUP_ID_INVALID`Groups	Status400fix the request	MeaningInvalid group id.	What to doUse 1203…@g.us.
`GROUP_NOT_FOUND`Groups	Status404fix the request	MeaningThe number is not in that group.	What to doList groups first.
`GROUPS_UNAVAILABLE`Groups	Status502retryable	MeaningWhatsApp did not return the groups.	What to doRetry shortly.
`URL_PORT_NOT_ALLOWED`Webhooks	Status400fix the request	MeaningOnly ports 443 / 80.	What to doUse the default https port.
`URL_PRIVATE_ADDRESS`Webhooks	Status400fix the request	MeaningURL points to a private / internal address.	What to doUse a public https URL.
`WEBHOOK_EVENTS_INVALID`Webhooks	Status400fix the request	MeaningUnknown event type.	What to doSee GET /v2/webhooks/events.
`WEBHOOK_URL_NOT_SET`Webhooks	Status400fix the request	MeaningNo webhook URL set.	What to doPUT the webhook first.
`WEBHOOK_VERSION_INVALID`Webhooks	Status400fix the request	Meaningversion must be 2.	What to doUse 2.
`WEBHOOK_DELIVERY_NOT_FOUND`Webhooks	Status404fix the request	MeaningDelivery not found.	What to doKept 7 days.
`NO_NUMBER`Webhooks	Status409fix the request	MeaningAdd a number first.	What to doEvents always belong to a number.
`WEBHOOK_DISABLED`Webhooks	Status409fix the request	MeaningThe webhook is disabled (receiver answered 410).	What to doSave the URL again.
`DELIVERY_PAYLOAD_EXPIRED`Webhooks	Status410fix the request	MeaningRedelivery is possible only during the retry window (~1 h).	What to doRebuild the state from your side (e.g. GET /v2/messages/{id}).
`LINK_FIELD_INVALID`Website button & links	Status400fix the request	MeaningA link field is invalid (details.field, details.reason).	What to doFix the named field (message ≤ 1000, utm values ≤ 150).
`LINK_NUMBER_INVALID`Website button & links	Status400fix the request	MeaningnumberId is not one of your numbers.	What to doUse an id from GET /v2/numbers.
`LINK_NUMBER_NO_PHONE`Website button & links	Status400fix the request	MeaningThe number was never linked: its phone is unknown.	What to doLink the number first.
`LINK_SLUG_INVALID`Website button & links	Status400fix the request	MeaningCustom slug: 3–40 lower-case letters, digits or dashes.	What to doOmit slug for a random unguessable one.
`LINK_SLUG_RESERVED`Website button & links	Status400fix the request	MeaningThis slug is a reserved word.	What to doChoose another slug.
`WIDGET_DOMAIN_INVALID`Website button & links	Status400fix the request	MeaningAn allowed domain is not a valid website domain.	What to doUse host names like example.com or *.example.com (no paths).
`WIDGET_DOMAINS_REQUIRED`Website button & links	Status400fix the request	MeaningAt least one allowed website domain is required.	What to doSend allowedDomains, e.g. ["example.com"].
`WIDGET_DOMAINS_TOO_MANY`Website button & links	Status400fix the request	MeaningToo many allowed domains (max 20).	What to doUse a wildcard like *.example.com.
`WIDGET_NAME_INVALID`Website button & links	Status400fix the request	MeaningName is required (1–80 characters).	What to doSend a short name.
`WIDGET_NUMBER_INVALID`Website button & links	Status400fix the request	MeaningnumberId (or an agent numberId) is not one of your numbers.	What to doUse an id from GET /v2/numbers.
`WIDGET_NUMBER_NO_PHONE`Website button & links	Status400fix the request	MeaningThe number was never linked: its phone is unknown.	What to doLink the number first.
`WIDGET_SETTINGS_INVALID`Website button & links	Status400fix the request	MeaningA widget setting is invalid (details.field, details.reason).	What to doFix the named field.
`LINK_CUSTOM_SLUG_PLAN`Website button & links	Status403fix the request	MeaningCustom link names need a paid plan.	What to doOmit slug (a random one is created) or upgrade.
`LINK_LIMIT_REACHED`Website button & links	Status403fix the request	MeaningYour plan allows no more WhatsApp links.	What to doDelete one or upgrade (growth: 50, business: unlimited).
`WIDGET_BRANDING_LOCKED`Website button & links	Status403fix the request	MeaningHiding "Powered by Mursilat" needs the Growth plan or higher.	What to doUpgrade, or keep branding.show = true.
`WIDGET_LIMIT_REACHED`Website button & links	Status403fix the request	MeaningYour plan allows no more website buttons.	What to doDelete one or upgrade (growth: 5, business: unlimited).
`WIDGET_ORIGIN_NOT_ALLOWED`Website button & links	Status403fix the request	MeaningPublic click from a site that is not in the allowed domains.	What to doAdd the domain to allowedDomains.
`LINK_NOT_FOUND`Website button & links	Status404fix the request	MeaningLink not found.	What to doCheck the linkId (GET /v2/links).
`WIDGET_NOT_FOUND`Website button & links	Status404fix the request	MeaningWebsite button not found.	What to doCheck the widgetId (GET /v2/widgets).
`LINK_SLUG_TAKEN`Website button & links	Status409fix the request	MeaningThis slug is already used.	What to doChoose another slug.
`WIDGET_CLICK_RATE_LIMITED`Website button & links	Status429retryable	MeaningLegacy: no longer returned. Over a burst limit the click answers 200 with ref null (the visitor still reaches WhatsApp).	What to doNothing to do.
`WIDGET_RATE_LIMITED`Website button & links	Status429retryable	MeaningToo many website-button requests from one network.	What to doRetry after Retry-After seconds.
`INTERNAL_ERROR`Server	Status500retryable	MeaningUnexpected error.	What to doRetry; contact support with the requestId.
`API_V2_NOT_CONFIGURED`Server	Status503retryable	MeaningAPI keys are not available yet on this server.	What to doRetry later.
`ENCRYPTION_NOT_CONFIGURED`Server	Status503retryable	MeaningSecrets cannot be stored safely right now.	What to doRetry later.
`SCHEDULING_UNAVAILABLE`Server	Status503retryable	MeaningScheduling is temporarily unavailable.	What to doSend now or retry later.