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.
| Code | HTTP | Meaning / what to do |
|---|---|---|
api_key_missing | 401 | No Authorization: Bearer am_live_… header. |
api_key_invalid | 401 | Key not recognised. |
api_key_revoked | 401 | Key was revoked in Settings → Developer. |
scope_missing | 403 | The key lacks the scope this endpoint needs (see each endpoint). |
plan_has_no_api_access | 403 | API access needs the Growth or Business plan. |
org_suspended | 403 | The business account is suspended. |
subscription_required | 402 | No active plan or trial. |
contact_not_found | 404 | Create the contact first (POST /v1/public/contacts). |
template_not_found | 404 | No approved template with that name and language. |
outside_service_window | 422 | More than 24 h since the customer last wrote — send an approved template instead of text. |
template_not_approved | 422 | Template is draft, pending, rejected or paused at Meta. |
no_consent | 422 | No recorded opt-in for this template category. |
no_marketing_consent | 422 | Marketing templates need marketing consent. |
contact_opted_out | 422 | The customer sent STOP; only replies inside the service window are possible. |
template_vars_invalid | 400 | Wrong number of variables or an empty variable. |
text_invalid | 400 | Empty text or more than 4096 characters. |
validation_failed | 400 | error.details lists the invalid fields. |
number_not_connected | 409 | The WhatsApp number is disconnected or still pending at Meta. |
rate_limited | 429 | More than 120 requests per minute for this key — retry after a short wait. |
send_failed | 502 | Meta 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.