Understand API errors

Route-level errors

• 401 unauthorized means the key is missing, invalid, or expired.
• 403 forbidden means scope or plan API access is unavailable.
• 400 invalid_request means JSON or required input is invalid.
• 403 PLAN_LIMIT_EXCEEDED includes quota resource, limit, current, and requested fields.
• 404 not_found protects missing or inaccessible broadcast identities.

Per-recipient send errors

• Results can include invalid_phone, sender_not_configured, sender_resolution_failed, template_not_found, template_rejected, template_sender_mismatch, and outside_customer_service_window.
• Other outcomes include rate_limited, meta_send_failed, consent restriction reasons, conversation_read_only_removed_number, persistence failures, and unknown_error.
• rate_limited currently appears in an individual direct-send result rather than as a route-level 429 response.
• Blocked and invalid broadcast recipients can be classified before any Meta send.

Error envelope

{
  "error": "Human-readable recovery context",
  "code": "machine_readable_code"
}

Recover safely

• Correct permanent recipient, consent, sender, template, policy, or request errors before a new attempt.
• Back off explicit transient rate or provider failures with bounded jitter.
• Inspect every direct-send result even when the HTTP response succeeded.
• Do not automatically repeat a mutation after an unknown outcome; reconcile message or broadcast identities first.