Errors
Every problem code the API can return, what it means and what to do.
Errors are application/problem+json (RFC 9457). Switch on code: it never changes. doc_url links here.
| Code | HTTP | Title | Meaning |
|---|---|---|---|
aal2_required | 403 | Two-factor sign-in required | Sign in again with two-factor authentication to do this. |
account_suspended | 403 | Account suspended | This account is suspended. Contact support to restore it. |
ad_account_not_ready | 422 | Ad account is not ready | The connected ad account is not finished setting up on Meta's side yet. |
addon_not_available | 422 | Add-on not available | This add-on cannot be bought on your current plan. |
adult_learners_only | 422 | Adult learners only | This pack may only be sold to adult learners. |
ai_rate_limited | 429 | Too many AI requests | The assistant is being asked to do too much too quickly. Wait a minute and try again. |
already_exists | 409 | Already exists | Something with these details already exists. |
appeal_window_closed | 409 | Appeal window closed | The time allowed to appeal this decision has passed. |
below_minimum | 422 | Below the minimum | The amount is below the minimum allowed. |
business_verification_failed | 422 | Business verification failed | Meta could not verify this business. Fix the details in Business Manager and try again. |
channel_busy | 409 | Channel is busy | This channel is already running another job. Wait for it to finish. |
channel_not_ready | 422 | Channel is not ready to send | This channel is not connected or not approved to send yet. |
channel_rate_limited | 429 | Channel send rate limit exceeded | WhatsApp is throttling this number. Sending will resume shortly. |
channel_unhealthy | 422 | Channel needs attention | This channel has a problem that must be fixed before it can be used. |
confirmation_required | 422 | Confirmation required | Confirm this action to continue. |
conflict | 409 | Conflict | Someone changed this at the same moment. Retry the request. |
consent_missing | 422 | No consent to message this contact | This contact has not opted in, so you cannot message them. |
contact_opted_out | 422 | Contact has opted out | This contact asked to stop receiving messages. |
country_locked | 409 | Country is locked | The billing country cannot be changed once a subscription is active. |
coupon_invalid | 422 | Coupon is not valid | This coupon code is wrong, expired, or does not apply to this plan. |
daily_limit_reached | 422 | Daily spending limit reached | This action would go over the daily spending limit set for the assistant. Raise the limit in Settings or try again tomorrow. |
degraded | 503 | Temporarily degraded | We are running slowly right now. Try again in a few seconds. |
discount_rejected | 422 | Discount rejected | The store would not accept this discount. |
entitlement_required | 402 | Your plan does not include this | This feature is not part of your plan. Upgrade to use it. |
export_expired | 410 | Export expired | This export has expired. Generate a new one. |
feature_unavailable | 422 | Not available | This feature is not available for this account, channel or region. |
forbidden | 403 | Forbidden | You do not have access to this. |
four_eyes_required | 409 | Second approver required | Another authorised person must approve this before it can happen. |
gone | 410 | Gone | This link or resource no longer exists. |
helper_invalid | 422 | Helper is not valid | This helper's configuration is incomplete or invalid. |
idempotency_in_progress | 409 | A request with this Idempotency-Key is in progress | The same request is still being processed. Wait and read the result. |
idempotency_key_required | 400 | Idempotency-Key header is required | This write needs an Idempotency-Key header. |
idempotency_key_reuse | 422 | Idempotency-Key was reused with a different request | This Idempotency-Key was already used for a different request body. |
impersonation_denied | 403 | Impersonation denied | Staff impersonation is not allowed for this action or account. |
impersonation_inactive | 403 | Staff session is not active | This staff session is no longer active. Start a new one. |
impersonation_org_locked | 403 | Account locked for staff sessions | This account has blocked staff access. |
impersonation_read_only | 403 | View-as sessions are read-only | A view-as staff session cannot change anything. |
insufficient_balance | 402 | Insufficient balance | Your wallet does not have enough balance. Top up to continue. |
insufficient_call_balance | 402 | Insufficient call balance | Your calling balance is too low to place this call. Top up to continue. |
insufficient_scope | 403 | Insufficient scope | This API key or token is missing the scope this endpoint needs. |
integration_connect_failed | 422 | Could not connect the integration | We could not complete the connection. Try connecting again. |
integration_credentials_missing | 409 | Integration credentials missing | This integration has no saved credentials. Connect it first. |
integration_not_connected | 409 | Integration is not connected | Connect this integration before using it. |
integration_reauth_required | 409 | Integration needs reconnecting | This integration's access expired. Reconnect it. |
integration_scope_missing | 409 | Integration permission missing | The connected account did not grant a permission this needs. Reconnect and approve it. |
internal_error | 500 | Internal error | Something went wrong on our side. Try again; contact support if it keeps happening. |
invalid_api_key | 401 | Invalid API key | This API key is wrong, revoked or expired. |
invalid_cursor | 400 | Invalid cursor | The pagination cursor is not valid. Start from the first page. |
invalid_graph | 422 | Flow is not valid | This flow has a broken or unreachable step. |
invalid_request | 400 | Invalid request | The request was not understood. |
invalid_signature | 401 | Invalid signature | The webhook signature did not verify. |
invalid_token | 401 | Invalid token | This token is not valid. |
ip_not_allowed | 403 | IP address not allowed | This API key is restricted to other IP addresses. |
kyc_required | 422 | Verification required | Complete business verification before using this. |
link_blocked | 422 | Link blocked | A link in this message is blocked. Remove or replace it. |
lint_failed | 422 | Checks failed | This content did not pass our checks. Fix the reported problems. |
locked | 423 | Locked | Too many failed attempts. This is locked for a while. |
marketing_paused | 409 | Marketing is paused | Marketing sends are paused for this account right now. |
media_invalid | 422 | Media is not valid | This file cannot be used: wrong format, too large, or unreadable. |
meta_payment_required | 402 | Meta payment method has insufficient funds | Meta rejected the send because the WhatsApp payment method has no funds. |
meta_policy_blocked | 422 | Blocked by Meta policy | Meta blocked this because of their messaging policy. |
meta_rate_limited | 429 | Meta rate limit exceeded | Meta is throttling this account. Try again shortly. |
method_not_allowed | 405 | Method not allowed | This endpoint does not accept that HTTP method. |
no_calling_number | 422 | No calling number | Add a phone number for calls first, then try again. |
no_eligible_recipients | 422 | No eligible recipients | Nobody in this audience can be messaged right now. |
not_acceptable | 406 | Not acceptable | We cannot produce any of the formats you asked for. |
not_eligible | 422 | Not eligible | This account or record does not qualify for this action. |
not_found | 404 | Not found | We could not find this. It may have been deleted, or belong to another workspace. |
number_not_dialable | 422 | Number cannot be dialled | This phone number cannot be called from your account. |
oauth_not_configured | 503 | Sign-in provider not configured | This sign-in method is not set up on this deployment. |
otp_budget_exhausted | 429 | Too many codes sent | Too many verification codes were sent. Try again later. |
otp_invalid | 422 | Code is wrong | That verification code is wrong or has expired. |
otp_locked | 429 | Verification locked | Too many wrong codes. Verification is locked for a while. |
otp_required | 403 | Verification code required | Enter the verification code we sent you. |
override_limit_exceeded | 403 | Override limit reached | You have used all the manual overrides allowed in this period. |
pack_exceeds_mandate_limit | 422 | Pack exceeds your auto-pay limit | This top-up is larger than the auto-pay mandate allows. Raise the mandate or pick a smaller pack. |
payload_too_large | 413 | Payload too large | The request or file is too large. |
payment_evidence_required | 422 | Payment evidence required | Attach proof of payment before continuing. |
payment_method_required | 409 | Payment method required | Add a payment method to continue. |
payout_details_required | 409 | Payout details required | Add your bank or payout details before you can be paid out. |
permission_missing | 422 | Permission missing | The connected account is missing a permission this needs. |
phone_not_verified | 422 | No verified mobile number | Add and verify your mobile number in your profile first. |
phone_verification_required | 403 | Verify your mobile number before sending | Verify your mobile number before sending messages or offers. |
precondition_failed | 422 | Precondition failed | Something this depends on is not in place yet. |
provider_not_configured | 503 | Provider not configured | This provider is not set up on this deployment. |
publish_blocked | 422 | Publishing blocked | This cannot be published until the reported problems are fixed. |
quota_exceeded | 422 | Plan limit reached | You have reached a limit on your plan. Upgrade or wait for it to reset. |
quote_expired | 409 | Quote expired | This price quote has expired. Fetch a new one. |
quote_mismatch | 409 | Quote no longer matches | The price changed since you were quoted. Review the new price. |
rate_limited | 429 | Rate limit exceeded | Too many requests. Slow down and retry after the given delay. |
recently_asked | 409 | Asked too recently | This contact was asked recently. Wait before asking again. |
recipient_invalid | 422 | Number cannot receive messages | This number is not on WhatsApp, or cannot receive messages from you. |
region_not_available | 422 | Not available in this region | This is not available in your country yet. |
reveal_reason_required | 400 | Reason required | Give a reason before revealing this data. |
review_policy_violation | 422 | Against review policy | Asking for a review this way breaks the platform's review policy. |
role_forbidden | 403 | Your role cannot do this | Your role does not allow this. Ask an owner or admin. |
route_not_found | 404 | Route not found | There is no endpoint at this path. |
routing_standby | 422 | Another agent holds this conversation | Another teammate is handling this conversation right now. |
run_not_started | 422 | Run has not started | This run has not started yet, so there is nothing to act on. |
schedule_too_far | 422 | Scheduled too far ahead | That date is further ahead than we allow. Pick a nearer one. |
schedule_too_soon | 422 | Scheduled too soon | That time is too close to now. Pick a later one. |
second_confirmation_required | 409 | Second confirmation required | Confirm once more to go ahead with this irreversible action. |
second_tap_required | 422 | Confirm on screen | The final confirmation has to be an on-screen tap, not a chat reply. |
spend_confirmation_mismatch | 422 | Spend confirmation does not match | The amount you typed to confirm does not match the amount being spent. |
spend_confirmation_required | 422 | Confirm the amount | Type or tap to confirm the amount being spent. |
staff_only | 403 | Staff only | This is a Wapitick staff endpoint. |
staff_session_blocked | 403 | Blocked during a staff session | Messages to customers are never sent while Wapitick staff are signed in to your account. |
staff_session_expired | 401 | Staff session expired | This staff session has expired. Sign in again. |
state_conflict | 409 | Not allowed in this state | This cannot be done while the record is in its current state. |
step_up_required | 403 | Re-authentication required | Confirm your identity again to do this. |
tax_id_required | 422 | Tax id required | Add your GSTIN or tax id before continuing. |
template_lint_failed | 422 | Template checks failed | This template breaks a WhatsApp rule. Fix the reported problems. |
template_not_approved | 422 | Template is not approved | This template is not approved by WhatsApp yet. |
template_required | 422 | A template message is required | The 24-hour window is closed, so you must send an approved template. |
test_mode_only | 403 | Test mode only | This action only works with a test key (wk_test_) or in the test workspace. |
test_mode_unsupported | 403 | Not available in test mode | Test keys cannot do this. Use a live key, or see the test mode guide for what test mode covers. |
test_not_sent | 422 | Send a test first | Send yourself a test before publishing this. |
test_required | 409 | Test run required | Run a test before turning this on. |
token_expired | 401 | Token expired | Your session expired. Sign in again. |
token_revoked | 401 | Token revoked | This session was signed out. Sign in again. |
trust_tier_limit | 422 | Trust tier limit reached | New accounts have lower sending limits. This will rise as your account builds history. |
turnstile_failed | 422 | Bot check failed | The bot check did not pass. Try again. |
unauthenticated | 401 | Authentication required | Sign in to continue. |
undo_window_elapsed | 409 | Too late to undo | The time allowed to undo this has passed. |
unsafe_link | 422 | Unsafe link | A link in this content looks unsafe. Remove or replace it. |
unsupported_integration | 422 | Integration not supported | We do not support this integration here. |
unsupported_media_type | 415 | Unsupported media type | This file type is not accepted. |
upstream_error | 502 | Upstream error | A provider we depend on returned an error. Try again. |
upstream_timeout | 504 | Upstream timeout | A provider we depend on took too long. Try again. |
upstream_unavailable | 503 | Upstream unavailable | A provider we depend on is unavailable. Try again shortly. |
url_not_allowed | 422 | URL not allowed | This URL is not allowed here. |
validation_failed | 400 | Validation failed | One or more fields are wrong. See errors for the field pointers. |
window_closed | 422 | The customer service window is closed | More than 24 hours have passed since the customer's last message, so only templates can be sent. |
workspace_forbidden | 403 | No access to this workspace | You are not a member of this workspace. |
workspace_required | 400 | Workspace required | Pick a workspace (send the wapitick-workspace header). |