Handle API rate limits

Current rate-limit contract

Observable rate-limit outcome

A known upstream Meta rate error can become rate_limited for an individual direct-send result. The internal send service classifies it with 429 semantics before the batch endpoint returns it inside results, so callers must inspect per-recipient outcomes rather than waiting only for an HTTP 429.

Client strategy

1. Step 1

   Bound concurrency

   Use a small controlled worker pool rather than unbounded parallel requests.

2. Step 2

   Honor Retry-After

   Stop complaint requests for the indicated interval after a route-level 429.

3. Step 3

   Inspect each result

   For message sends, separate accepted recipients from rate_limited and permanent failures.

4. Step 4

   Stop unsafe repetition

   Do not retry permanent errors or unknown mutation outcomes automatically.

Other limits

• Direct sends support at most 50 parsed recipients per request.
• Broadcast creation follows the account monthly campaign quota.
• Provider throughput, quality, messaging tier, template, and consent controls remain separate from HTTP request rate.
• Monitor current account and provider evidence instead of inferring capacity from a successful prior request.