Capacity, Quality & Limits

API Rate Limits

Rate limiting can occur even when your account is healthy. Two common modes:

• Request-rate limit — returns 429 when request-per-second thresholds are exceeded.
• Concurrent-load limit — returns 503 when upstream systems are temporarily overloaded.

If either appears:

1. Slow down request pace immediately.
2. Use queue-based traffic shaping.
3. Retry with exponential backoff and jitter.

For error code details, see Meta API Error Reference.

Messaging Limits (Portfolio-Level)

Messaging limits define how many unique users your business can message outside the customer service window in a rolling 24-hour period.

Limits are shared at the Meta Business Portfolio level — all numbers in the same portfolio consume the same messaging pool.

Typical tiers:

Important: User-initiated conversations are not counted toward this limit. Limits only apply to business-initiated outreach outside the service window.

Legacy vs Current Limit Fields

Meta shifted to portfolio-level limit handling on October 7, 2025. Some older limit-related fields were gradually phased out after that date.

Dualhook prefers current portfolio-level fields when present and keeps compatibility with legacy fields for backward support.

Increasing Limits

Limit growth happens in stages:

1. Scale from 250 to 2,000
2. Scale from 2,000 upward (10K, 100K, UNLIMITED)

Common qualification factors:

• Business verification path completion
• Consistent high-quality messaging
• Sufficient recent usage of current limit

After eligibility is met, upgrades are often applied automatically within a few hours.

Automatic Scaling Beyond 2,000

Meta evaluates:

• Message quality across numbers and templates
• Utilization of current limit over the last 7 days

If criteria are satisfied, the portfolio moves up one tier automatically.

Quality Rating

Quality is based on recent user feedback signals, weighted by recency:

• Blocks
• Reports
• Read/engagement behavior
• Negative feedback patterns

When quality degrades:

• Upgrade eligibility can be delayed
• Sending restrictions can appear
• Health may move from AVAILABLE to LIMITED or BLOCKED (see Health Monitoring)

Template Quality States

Template-level quality is tracked separately from number-level health.

Low template quality can lead to pauses or disablement even if account-level access is still active.

Check Current Status

curl -X GET "https://graph.facebook.com/<GRAPH_VERSION>/<PHONE_NUMBER_ID>?fields=health_status,quality_rating,whatsapp_business_manager_messaging_limit,messaging_limit_tier" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

{
  "id": "<PHONE_NUMBER_ID>",
  "health_status": {
    "can_send_message": "AVAILABLE",
    "entities": []
  },
  "quality_rating": "GREEN",
  "whatsapp_business_manager_messaging_limit": "TIER_10K",
  "messaging_limit_tier": "TIER_10K"
}

Webhook Signals to Monitor

Dualhook surfaces management events for operations monitoring. See Webhook Events for the complete event list.

phone_number_quality_update

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "event": "QUALITY_UPDATED",
            "phone_number_id": "<PHONE_NUMBER_ID>",
            "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
            "current_limit": "TIER_2K",
            "current_quality_rating": "YELLOW",
            "previous_quality_rating": "GREEN"
          }
        }
      ]
    }
  ]
}

business_capability_update

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "business_capability_update",
          "value": {
            "event": "increased_capabilities_eligibility_deferred"
          }
        }
      ]
    }
  ]
}

Monitoring Locations

Use both product and Meta surfaces:

• Dualhook dashboard — webhook-driven health and limit/quality signals
• WhatsApp Manager — Messaging Limits and account insights
• Meta Account Quality — business.facebook.com/accountquality

Operational Playbook

If quality drops or limit upgrades stall:

1. Reduce promotional volume and tighten audience targeting.
2. Send only to recently opted-in users.
3. Improve template relevance and frequency control.
4. Monitor blocks/reports daily and pause weak campaigns quickly.
5. Resume scale gradually only after sustained quality recovery.

For a comprehensive health maintenance strategy, see Maintain Account Health.