APIMASTERDevelopersHelp centerOpen app

Errors

Errors return a non-2xx status and a JSON body:

{ "error": { "code": "outside_service_window", "details": null } }

Branch on error.code, never on the message text.

CodeHTTPMeaning / what to do
api_key_missing401No Authorization: Bearer am_live_… header.
api_key_invalid401Key not recognised.
api_key_revoked401Key was revoked in Settings → Developer.
scope_missing403The key lacks the scope this endpoint needs (see each endpoint).
plan_has_no_api_access403API access needs the Growth or Business plan.
org_suspended403The business account is suspended.
subscription_required402No active plan or trial.
contact_not_found404Create the contact first (POST /v1/public/contacts).
template_not_found404No approved template with that name and language.
outside_service_window422More than 24 h since the customer last wrote — send an approved template instead of text.
template_not_approved422Template is draft, pending, rejected or paused at Meta.
no_consent422No recorded opt-in for this template category.
no_marketing_consent422Marketing templates need marketing consent.
contact_opted_out422The customer sent STOP; only replies inside the service window are possible.
template_vars_invalid400Wrong number of variables or an empty variable.
text_invalid400Empty text or more than 4096 characters.
validation_failed400error.details lists the invalid fields.
number_not_connected409The WhatsApp number is disconnected or still pending at Meta.
rate_limited429More than 120 requests per minute for this key — retry after a short wait.
send_failed502Meta rejected the message; error.details carries Meta's error code.

Retry only 429 and 5xx (with backoff). 4xx needs a change in your request or data.