Troubleshoot CARRIER_RATE_LIMITED on bulk number purchase

A bulk purchase (POST /api/v1/numbers/buy-bulk, up to 50 rows in one call) processes row by row. When one row hits a carrier-side rate limit (HTTP 429), Orbit stops pulling new rows from the batch — the breaker trips — and every remaining row is stamped with error.code = "CARRIER_RATE_LIMITED" in the failed[] array without another carrier call. A 50-row batch can come back 200 OK with, for example, 12 rows in succeeded[] and 38 rows in failed[], all marked CARRIER_RATE_LIMITED. That shape means: nothing is stuck, nothing was charged for the skipped rows, and the fix is to retry only the failed rows a few seconds later.

Only the per-row error RATE_LIMITED (the row whose carrier call actually returned 429) and the breaker-skip marker CARRIER_RATE_LIMITED trigger the stop. Deterministic per-row failures (validation, compliance gates, inventory races) do not trip the breaker — see Troubleshoot number purchase failures for those.

Cause table

Cause	How it reads	Recover by
Parallel bulk writes from your own tenant	Two `buy-bulk` calls (or a bulk call plus retries of an earlier one) run at once and jointly exceed the carrier’s per-key ceiling	Run one bulk call at a time per tenant; stagger follow-up batches
Carrier-side bulk throttle under shared load	The upstream carrier rate-limits purchase traffic globally, so even a single 50-row batch can trip the breaker mid-flight	Wait a few seconds and retry the failed slice; if the same pattern persists after a handful of retries, escalate (below)

Fix table

Step	Do this
1. Read the gate right	Check `succeeded.length` — the response is `200 OK` even when rows fail, so never branch on the status code
2. Retry the failed slice only	Collect the `phone_number` (plus `country_code` and `id` if you carry them) from each `failed[]` row and re-submit exactly those in a new `buy-bulk` call
3. Back off briefly	Wait a few seconds before the retry so the carrier window clears; keep retries serial, never parallel
4. Never re-run the whole batch	`succeeded[]` rows already own their numbers — re-running them wastes a rate-limit window and risks inventory-gone failures

Example: failure shape and recovery

The bulk response splits successful rows from skipped ones; debited_cents covers only what succeeded:

{
  "data": {
    "order_id": "numOrder_01J9Z8ABCDEF",
    "succeeded": [
      { "id": "num_abc123", "phone_number": "+14155550100", "status": "active" }
    ],
    "failed": [
      {
        "phone_number": "+14155550101",
        "error": {
          "code": "CARRIER_RATE_LIMITED",
          "message": "The carrier rate-limited the batch. Some numbers were skipped — retry the failed rows in a few seconds."
        }
      },
      {
        "phone_number": "+14155550102",
        "error": {
          "code": "CARRIER_RATE_LIMITED",
          "message": "The carrier rate-limited the batch. Some numbers were skipped — retry the failed rows in a few seconds."
        }
      }
    ],
    "total_cost_cents": 450,
    "debited_cents": 150
  }
}

Recovery call — take each failed[].phone_number, wait a few seconds, and submit exactly that slice (never the original batch):

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/buy-bulk \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "phone_number": "+14155550101", "country_code": "US" },
      { "phone_number": "+14155550102", "country_code": "US" }
    ]
  }'

The batch returns a pollable order_id; failed rows are never charged, so re-submitting them is billing-safe.

When to retry vs escalate

Retry the failed slice after a few seconds. Escalate when the same pattern recurs after a handful of spaced retries — that points to a sustained carrier-side throttle, which only the operator can clear. Open a ticket with:

The exact meta.request_id of the failing bulk call — a wildcard or partial id is rejected when support queries logs.
The batch’s order_id (pollable via the bulk-order history endpoints).
The carrier name from error.details.carrier, if the per-row error carries one, and the country code of the failed numbers.

Reference

Troubleshoot CARRIER_RATE_LIMITED on bulk number purchase

Troubleshoot CARRIER_RATE_LIMITED on bulk number purchase

Cause table

Fix table

Example: failure shape and recovery

When to retry vs escalate

See also

​Troubleshoot CARRIER_RATE_LIMITED on bulk number purchase

​Cause table

​Fix table

​Example: failure shape and recovery

​When to retry vs escalate

​See also

Troubleshoot CARRIER_RATE_LIMITED on bulk number purchase

Cause table

Fix table

Example: failure shape and recovery

When to retry vs escalate

See also