Skip to main content

​
Troubleshooting: US toll-free sender blocked with TFV_REQUIRED

US carriers (Verizon, AT&T, T-Mobile) treat A2P SMS and MMS from unverified toll-free numbers as guaranteed-throttle traffic — they filter it, cap it to a trickle, or drop it entirely. To keep that send from burning credits on a guaranteed-no-deliver request, Orbit’s send preflight rejects the request synchronously with 422 TFV_REQUIRED until your sender’s tfv_status reads approved. The message is never queued and never handed to a carrier.
The gate refuses the send before it is queued, so a retry loop only re-trips the 422. The move is a one-time verification filing, not a retry schedule.

​
Match the status to its meaning

The error body names the status so you do not have to guess which lane you are in:
The message text changes per status: pending says the review is in flight (expect 1–3 business days), and rejected asks you to amend the use-case and sample messages and re-submit.

​
Reproduce the block

Send an SMS or MMS where from is a toll-free number on your account and to is a US recipient:
While that number’s verification is unfinished, the response is a 422 with the shape above.

​
Confirm the number’s status

Two read-backs tell you where the number stands.
  1. The account-level trust hub. Call GET /api/v1/brand-identity/status and find the messaging_toll_free entry — a gated number shows that channel at action_required with a detail like “1 of 3 numbers verified”, and it raises the nextActions priority list accordingly:
  2. The number itself. Open Settings → Numbers in the dashboard and read the number’s Toll-Free Verification status, or query the number list over the API — every toll-free row carries a tfv_status field (not_submitted when no filing exists).
A detail on the brand-identity hub that counts verified toll-free numbers is the fastest sweep: it tells you whether the gate will fire for every toll-free sender on the account, not just the one that tripped.

​
Submit Toll-Free Verification

Verification is a carrier-side filing Orbit submits on your behalf — the information comes from you, the queue belongs to the carrier.
  1. Open Settings → Compliance in the dashboard and start the Toll-Free Verification form for the gated number.
  2. Fill in the business details (name, website, contact email and phone) plus the fields carriers screen the filing on:
    • a use case label (the category list mirrors the carriers’ fixed enum — 2FA, Marketing, Customer Care, and so on);
    • a use-case summary describing the traffic you actually send;
    • one to five sample messages copied from your live templates.
  3. Submit. The number’s tfv_status moves to pending immediately, and the carrier review typically clears in 1–3 business days.
  4. Send again once the status flips to approved — the gate drops that entry from its block list without any change on your integration.
Carriers review the filing against what you declare, so an accurate use case and real sample messages clear faster than a generic one. Lead times are expectations, not guarantees.

​
Wait for the review

While tfv_status is pending, the carrier decides — not Orbit. Do not retry the blocked sends in a loop: they return the same 422 and burn rate-limit budget without changing the outcome. Poll the status with the read-backs above and queue or hold the traffic until the filing clears. If a pending status sits well past a week, that is escalation territory — see Escalation.

​
Recover from rejected

A rejected status is terminal like pending is not: only a new filing moves the number back into review.
  1. Read the rejection note on the number’s compliance card — Settings → Numbers → the number → Toll-Free Verification — or in the messaging_toll_free channel’s reason on the brand-identity hub.
  2. Amend what the carrier named. In practice the decline lands on the use case (does not match the traffic) or the sample messages (do not demonstrate the declared use). Resubmitting an unchanged form earns a faster second rejection.
  3. Re-submit the amended form through the same Settings → Compliance path. The status re-enters review at pending with a fresh 1–3 business-day expectation.

​
Scope of the gate

The preflight is deliberately narrow. It fires only when all of these hold at once:
  • the sender is a toll-free number owned on your account (platform pool senders and shared defaults bypass it);
  • the channel is SMS or MMS — voice, email, WhatsApp, RCS, and the other channels never consult TFV;
  • the recipient resolves to US (by the account’s country hint, or the +1 NANP prefix when no hint is sent).
Everything else is unaffected: non-US destinations, non-toll-free senders, and every channel other than SMS/MMS send exactly as before.

​
Escalation

Escalate to support when the fix above cannot land — a pending filing that has sat for over a week, or a rejected verdict whose reason you cannot resolve with the documents you hold. Include:
  1. The toll-free number (E.164) and the destination country.
  2. The current tfv_status — copied from Settings → Numbers or the messaging_toll_free entry on GET /api/v1/brand-identity/status.
  3. The message ID or request ID from a rejected send (error.code plus meta.request_id), and the timestamp with timezone.
  • Sender-ID Registration — the broader registration lifecycle for alphanumeric senders and the pending → approved / rejected statuses.
  • Brand Identity API — the consolidated trust-posture read used above, with the toll-free channel key and the next-actions list.
  • Error Codes — the full table where TFV_REQUIRED is catalogued alongside the other 422 gates.
  • FAQ — the shorter one-paragraph summary of this same gate.