Troubleshoot push broadcast pre-send gates

BROADCAST_TOO_LARGE (422) and CHANNEL_RATE_LIMITED (429) are deterministic pre-send refusals, not provider failures: your broadcast never reaches APNs / FCM / HMS / Web Push, so nothing is dispatched and no wallet hold is taken. Both gates fire on the whole-org broadcast surface — user_ids: ["*"] on POST /api/v1/push/send, or channel: "push" on the unified POST /api/v1/messages pipeline — and both are tenant-owned controls you can deliberately size. This page answers: which gate fired, where the ceiling is sized, how to read the cause from the details envelope, and the one re-send that verifies the fix.

A push wildcard send is user_ids: ["*"], not device_token_ids. The audience cap (this page) counts the deliverable audience — enabled device tokens minus push/all suppression opt-outs — not the raw row count. Provider-side per-device verdicts (APNs 410 / FCM UNREGISTERED, token expiry) return 201 and grade per device in notifications[]; decode those on Push token expiry.

The two gates

Code	HTTP	Gate	Where the ceiling is sized
`BROADCAST_TOO_LARGE`	422	The audience-size gate on the dedicated `POST /api/v1/push/send` route: a wildcard (`user_ids: [""]`) whose deliverable audience exceeds the platform fan-out ceiling of 100,000 devices*.	Platform constant — never tenant-configurable. Split into explicit `user_ids` lists, or narrow via suppression scope.
`CHANNEL_RATE_LIMITED`	429	The per-channel velocity gate from the cross-channel fraud guard, over a sliding one-minute window. Push shares the `push` channel bucket with every unified-pipeline (`POST /api/v1/messages`) send.	Your per-channel envelope — `GET` / `PUT /api/v1/settings/compliance/channel-rate-overrides` (see Per-channel rate overrides), plus the fraud-floor ceiling the Fraud caps page lists for `push`.

Distinguish the envelope a refusal came from:

Dedicated push route (POST /api/v1/push/send with user_ids: ["*"]) → only BROADCAST_TOO_LARGE (audience gate) applies pre-flight. Neither gate fires per-device; per-device sent/skipped/failed rows sit in the notifications[] array of a 201.
Unified pipeline (POST /api/v1/messages with channel: "push") → every per-channel fraud gate (rate cap → spend cap → blocklist) runs before the dedicated send executes; CHANNEL_RATE_LIMITED surfaces here.

A broadcast that fans out through the unified pipeline (for example a POST /api/v1/messages fan-out) can also trip the spend-cap codes (SMS_DAILY_SPEND_CAP / CHANNEL_DAILY_SPEND_CAP / VOICE_DAILY_SPEND_CAP) on the same request — the per-channel ops ceilings. Those are covered on Spend-cap refusals; this page covers the rate and audience caps only.

Cause table

Read the error.details envelope from the refusal to scope which lever to pull.

`BROADCAST_TOO_LARGE` (422)	What the gate counted	Tenant pull
Audience exceeds 100,000 deliverable devices	The gate pre-counts deliverable tokens: `enabled = TRUE` device rows minus active suppression (`channel = 'push'` OR `'all'`) rows — not the raw table size. A row disabled via the per-device `enabled` flag, or a user on the suppression list, never counts.	Split the audience into explicit `user_ids` batches, or narrow it: re-send to a subset (e.g. segment by `user_id` tier) — nothing in the code path truncates silently.
Broadcast aborts wholesale	The refusal is all-or-nothing: the platform rejects the entire wildcard before any device consumes a slot.	Re-send once with explicit `user_ids` (below) — do not log individual successes.

`CHANNEL_RATE_LIMITED` (429)	What the gate counted	Tenant pull
`push` per-minute cap tripped	A sliding one-minute window (not a fixed-minute bucket): current + weighted-previous counts, so a burst at the minute rollover cannot double-fire the cap. Push shares this bucket with every unified `POST /api/v1/messages` send on this tenant.	Throttle the burst, or raise the `push` per-minute override (owner-only) — see
Per-channel rate overrides.
`details.channel` says `push`	The gate always names its channel so push-throttling never merges silently with SMS/email velocity.	Read `details.channel` + `details.limit` before raising anything — a `sms` refusal must be raised on `sms`, not on `push`.
Which channels blocked — from the `details` envelope	Other fraud pushes (mms, whatsapp, rcs, viber, email, telegram, web_chat, messenger, line, instagram, fax, apple_messages) each have their own bucket; the envelope’s `channel` field identifies which one saturated.	`GET /api/v1/settings/compliance/channel-rate-overrides` returns `overrides` + `defaults` for every channel in one read.

Fix table

Fix the gate at its own surface, then re-send once.

Code	Fix	Surface
`BROADCAST_TOO_LARGE`	Replace the wildcard with explicit `user_ids`; re-send one request.	`POST /api/v1/push/send` (dedicated route)
`CHANNEL_RATE_LIMITED` on push	Throttle the burst, or raise the `push` per-minute cap (owner-only) — e.g. `{"overrides": {"push": 500}}` on the whole `overrides` map (PUT replaces the map; send all channels you want active).	`PUT /api/v1/settings/compliance/channel-rate-overrides` (whole-map replace)
`CHANNEL_RATE_LIMITED` envelope that’s really a fraud floor	If the envelope says `channel: "push"` but the value is the platform floor (not your override), the fraud guard’s env floor is the ceiling — raise it only via the fraud-caps surface (`caps.push.max_per_min`).	`PUT /api/v1/settings/compliance/fraud-caps` (see Fraud caps)

What NOT to try

Retrying the identical payload. BROADCAST_TOO_LARGE never clears itself: the audience gate is a pure function of your token registry — re-running the same wildcard computes the same refusal and burns per-minute rate headroom on the whole API surface. Retry only after the audience is under the cap.
Splitting a wildcard into multiple wildcard sends. Two user_ids: ["*"] sends target the same 100,001+ devices and both refuse. Only explicit user_ids (or suppression narrowing) reduces the projected count.
Looping a 429 retry. The rate gate is a hard per-minute window — a tight retry loop just spends your own envelope inside the window. Back off ≥ the window (60s) before the first retry after a raise.
Assuming the refusal is a provider fault. Both codes are platform pre-flights; the provider was never called. If you saw 201 with per-device failed entries, this page is the wrong runbook — decode per-device verdicts on Push token expiry.

Surface the cause

Read the refused response’s error.details envelope — the ERROR_CODES member for both codes declares the same diagnostic shape:

`BROADCAST_TOO_LARGE` (422)

{
  "error": {
    "code": "BROADCAST_TOO_LARGE",
    "message": "Broadcast would target 128044 devices, exceeding the 100000 recipient limit. Use explicit user_ids or segments instead.",
    "status": 422
  },
  "meta": { "request_id": "req_01J9Z8ABCDEF", "timestamp": "2026-09-29T11:00:00Z" }
}

The message already counts the deliverable audience; the request_id is the handle to cite on escalation.

`CHANNEL_RATE_LIMITED` (429)

{
  "error": {
    "code": "CHANNEL_RATE_LIMITED",
    "message": "push rate limit exceeded: 100 sends/min",
    "status": 429,
    "details": { "channel": "push", "limit": 100, "window": "1m" }
  },
  "meta": { "request_id": "req_01J9Z8ABCDEF", "timestamp": "2026-09-29T11:00:00Z" }
}

details.channel scopes the lever: push here — raise push, never sms. The window: "1m" and limit values tell you what the sliding window evaluated.

Recovery sequence

Read the refusal envelope — confirm the exact code and details.channel before touching anything.

Fix the gate.

BROADCAST_TOO_LARGE: re-send to explicit user_ids —

curl -X POST https://api.orbit.devotel.io/api/v1/push/send \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["user_8a1f2c", "user_9b2e4d", "user_7c3f5a"],
    "title": "Order update",
    "body": "Order #12345 is ready for pickup"
  }'

CHANNEL_RATE_LIMITED on push: either throttle the burst and re-send ≥60s later, or raise the push override (owner-only) —

curl -X PUT https://api.orbit.devotel.io/api/v1/settings/compliance/channel-rate-overrides \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"overrides": {"push": 500}}'

Remember: PUT replaces the whole overrides map — send every channel you want active, or omitted channels revert to the cluster default instantly.

Re-send once. One clean request after the fix proves the gate re-evaluated; do not parallel-fan the re-send.
Verify. For the rate gate, GET /api/v1/settings/compliance/channel-rate-overrides must show your push override alongside the defaults entry. For the audience gate, the same payload now returns 201 with per-device results in notifications[].

When to escalate

Escalate only when the refusal persists after the fix on the surface the envelope names. Include:

Your tenant ID (GET /api/v1/me → organizationId).
The full error envelope — request_id, code, message, and details exactly as returned.
For BROADCAST_TOO_LARGE: the deliverable device count the message reported and the suppression scope in use.
For CHANNEL_RATE_LIMITED: the current push override value (GET /api/v1/settings/compliance/channel-rate-overrides) and the observed send rate.

A 422-versus-429 distinction matters to support: 422 (audience) never clears without a shape change; 429 (rate) clears on the next window once the cap room exists.

Reference

Troubleshoot push broadcast pre-send gates (BROADCAST_TOO_LARGE, CHANNEL_RATE_LIMITED)

Troubleshoot push broadcast pre-send gates

The two gates

Cause table

Fix table

What NOT to try

Surface the cause

`BROADCAST_TOO_LARGE` (422)

`CHANNEL_RATE_LIMITED` (429)

Recovery sequence

When to escalate

See also

​Troubleshoot push broadcast pre-send gates

​The two gates

​Cause table

​Fix table

​What NOT to try

​Surface the cause

​BROADCAST_TOO_LARGE (422)

​CHANNEL_RATE_LIMITED (429)

​Recovery sequence

​When to escalate

​See also

Troubleshoot push broadcast pre-send gates

The two gates

Cause table

Fix table

What NOT to try

Surface the cause

`BROADCAST_TOO_LARGE` (422)

`CHANNEL_RATE_LIMITED` (429)

Recovery sequence

When to escalate

See also