​

Troubleshooting: cooldown and rate-limit 429s

​

Common Verify / OTP 429 codes

​

Cross-channel 429 codes

​

Response shape

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry in 12 seconds.",
    "status": 429,
    "retry_after": 12
  },
  "meta": {
    "request_id": "req_01J9X4KZT8Q2M7W3N5VSP8DH6B",
    "timestamp": "2026-08-25T14:03:11.482Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
  }
}

​

Codes by surface

​

How to retry correctly

1. Read retry_after. Most 429 responses include a retry_after value (seconds) — wait that long before retrying rather than looping with a fixed delay.
2. Back off per recipient, not per batch. Per-recipient cooldowns fire on one recipient; other recipients in the same batch are unaffected, so retry only the limited rows.
3. Fix the loop. If one recipient keeps tripping VERIFY_RECIPIENT_RATE_LIMITED, the throttle is doing its job — check for a re-send loop in your client before bumping limits.

​

Backoff code

const MAX_RETRIES = 5;
const MAX_WAIT_SECONDS = 60;

async function sendWithBackoff(url, options) {
  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    const header = res.headers.get("retry-after");
    let body = null;
    try {
      body = await res.clone().json();
    } catch {
      // Non-JSON body — fall back to header or computed backoff
    }

    const bodyHint = body?.error?.retry_after;
    const headerHint = header !== null ? Number(header) : NaN;
    let waitSeconds =
      typeof bodyHint === "number" && bodyHint > 0
        ? bodyHint
        : Number.isFinite(headerHint) && headerHint > 0
          ? headerHint
          : Math.pow(2, attempt) + Math.random(); // 2^n s + 0–1s jitter
    waitSeconds = Math.min(waitSeconds, MAX_WAIT_SECONDS);

    if (attempt === MAX_RETRIES) {
      throw new Error(
        `Retry budget exhausted after ${MAX_RETRIES + 1} attempts (last code: ${
          body?.error?.code ?? "unknown"
        })`
      );
    }
    await new Promise((r) => setTimeout(r, waitSeconds * 1000));
  }
}

​

Identify which limiter fired

1. Read error.code on the 429. It names the limiter family — do not guess from the endpoint you called.
2. Starts with VERIFY_? A per-recipient gate fired. Cooldown or recipient-rate, keyed on that one phone number. See Rate-limit and cooldown taxonomy for how the recipient gates stack.
3. Starts with FREQUENCY_? A cap your org configured fired. Open the cap and check its window — see Frequency caps.
4. Ends in _MPS_EXCEEDED, or is CONCURRENCY_LIMIT_EXCEEDED / VOICE_COUNTRY_RATE_LIMITED? A tenant throughput ceiling fired. Your org is sending faster than its quota, not one recipient. Dashboard surfaces and quota tuning are in API key usage limits.
5. Is RATE_LIMITED or RATE_LIMIT_EXCEEDED? The shared fallback or the global HTTP quota. Treat it as tenant-wide throughput and follow step 4 unless you know the recipient-specific path raised it.

​

Do not retry

• VERIFY_RESEND_COOLDOWN is keyed on the recipient. Retrying the same phone number just re-trips the gate and counts against its send-rate budget. Drop that recipient from the batch, wait out the cooldown, and surface the countdown to the end user.
• FREQUENCY_CAP_EXCEEDED means the contact already received the allowed number of sends inside the rolling window. Retrying the same contact inside the window always fails. Skip the contact for this window; if legitimate traffic keeps hitting the cap, raise the cap itself in Frequency caps.

​

Fleet-wide 429s