Troubleshooting: sender and asset preflight gates

Four codes sit between your request and the carrier boundary, and all four refuse before anything queues, submits, or bills. Group them under one mental model: a sender or asset preflight gate judged the request against what that sender or asset can legally do, and the fix lives on your side — in the payload, the sender you picked, or a filing you have not finished.

Code	Gate	Why it refuses
`MMS_NANP_ONLY`	Channel fit on the send	MMS to a recipient outside the North American Numbering Plan (NANP). Carriers outside NANP silently drop MMS, so the platform stops it before your wallet is charged.
`NOT_SMS_CAPABLE`	Sender capability on the send	The sender you picked cannot carry SMS in the destination country — a voice-only or fax-capable number with no `sms` capability. Treated as permanent: no retry moves the outcome.
`TFV_LINT_BLOCKED`	Asset lifecycle (toll-free verification)	Your Toll-Free Verification filing tripped the pre-submit content lint — one or more sample messages match a carrier-disallowed vertical. Fix it now, before the carrier review queue bounces it days later.
`LOA_NOT_SIGNED`	Asset lifecycle (hosted messaging)	A hosted-messaging order can only reach the carrier once the Letter of Authorization is signed. No LOA signature, no submit.

None of these is retriable as-is. Each refuses deterministically before a queue or a carrier fan-out, so a retry loop earns the same refusal — and NOT_SMS_CAPABLE is explicitly classified as a permanent send error that retry suppression will not attempt again.

Match the channel, then the gate

Pick the lane first — the four codes split two ways.

What were you doing?

├─ Sending a message (SMS / MMS payload)?
│   ├─ MMS to a non-NANP recipient ............ MMS_NANP_ONLY
│   └─ sender has no SMS capability for the
│      destination country ................... NOT_SMS_CAPABLE
│
└─ Working an asset lifecycle (number/asset compliance filing)?
    ├─ Toll-Free Verification submission ....... TFV_LINT_BLOCKED
    └─ Hosted-messaging order submit ........... LOA_NOT_SIGNED

MMS_NANP_ONLY and NOT_SMS_CAPABLE fire on the send path against the payload and sender you chose. TFV_LINT_BLOCKED and LOA_NOT_SIGNED fire on an asset’s lifecycle endpoint — a toll-free-verification submission and a hosted-messaging order submit — and have nothing to do with the message transport until the asset clears.

Per-code cause table

Code	Where it fires	Root cause	Fix
`MMS_NANP_ONLY`	`POST /api/v1/messages/sms` (MMS payload)	`to` resolves outside NANP	Send the body as SMS-only to that recipient and let the cascade fall back, or keep MMS for NANP recipients only
`NOT_SMS_CAPABLE`	any SMS send	sender has no `sms` capability for the destination	Pick an SMS-capable sender, or pre-check `GET /api/v1/numbers/country-capabilities` before you map a sender
`TFV_LINT_BLOCKED`	`POST /api/v1/numbers/:id/tfv`	sample messages matched a disallowed-vertical pattern at error severity	Fix the flagged samples (`details.lint` in the envelope) and re-submit — the carrier would bounce it anyway
`LOA_NOT_SIGNED`	`POST /api/v1/numbers/hosted-messaging/:id/submit`	order’s LOA was never signed	Sign it with `POST /api/v1/numbers/hosted-messaging/:id/loa/sign`, then re-submit

`MMS_NANP_ONLY` — MMS outside North America

MMS as a media format only survives NANP carriers (US +1, Canada +1, and the extended-NANP islands). To any other destination the carrier drops the payload silently — and the wallet would still have been charged for the hand-off. The gate rejects the send at the API service layer and at the provider boundary, so the charge never happens. The error body names the recipient:

{
  "error": {
    "code": "MMS_NANP_ONLY",
    "status": 422,
    "message": "MMS is only supported for North American Numbering Plan destinations. Drop the media payload or cascade to SMS for this recipient.",
    "details": { "to": "+442071838750" }
  },
  "meta": { "request_id": "req_9f3a2b1c", "timestamp": "2026-09-12T14:22:01Z" }
}

The fix is never “retry” — decide what the recipient can receive:

Drop the media and send SMS. For non-NANP recipients, remove media_urls (and any MMS-only field) and let the body go as a plain SMS. The message cascade was built for exactly this fall-back.
Keep MMS for NANP recipients only. Segment your audience on the destination prefix (+1) and send the rich payload only to that segment.
Route through a channel that carries media to the destination. RCS and WhatsApp carry media to non-NANP recipients; MMS does not.

`NOT_SMS_CAPABLE` — the sender cannot carry SMS

A number has capabilities: sms, mms, voice, fax. A voice-only or fax-only number you handed to an SMS send has no sms flag, and the gate refuses rather than letting the dispatch fail downstream. The code is in the platform’s permanent-send-error retry suppression set — no retry attempt changes the outcome, and the response deliberately fails the recipient instead of burning retry budget. Two ways to stay ahead of it:

Pre-check the sender’s capabilities. Read GET /api/v1/numbers/country-capabilities before you map a sender to a country, and confirm the sender you picked advertises an sms capability for that destination’s line type in the response.
Inspect the number once you’ve bought it. Open Settings → Numbers in the dashboard and confirm the sms capability is on the row before wiring the number into a campaign or a sender pool.

The code is deliberately retained even where the live route emits a generic capability refusal — SDKs match on it as part of the permanent retry-suppression contract, so treat a NOT_SMS_CAPABLE response as terminal and fix the sender, not the schedule.

`TFV_LINT_BLOCKED` — toll-free filing refused by the content lint

The Toll-Free Verification submit (POST /api/v1/numbers/:id/tfv) runs a pre-submit content lint before the filing ever reaches the carrier-side TFV endpoint. The lint matches the sample messages against the well-known carrier disallowed-vertical list (SHAFT categories, payday loans, gambling, crypto promotion, debt collection, lead-gen, get-rich-quick, and phishing-shaped language). A match at error severity blocks the submission — catching a structural rejection in minutes instead of the 5+-business-day carrier review bounce, and keeping you off the 7-day amend window that starts counting the moment the carrier refuses.

{
  "error": {
    "code": "TFV_LINT_BLOCKED",
    "status": 422,
    "message": "TFV samples violate carrier content policy. Fix the highlighted issues before submitting — carrier rejection would cost 5+ business days and burn into the 7-day amend window.",
    "details": {
      "lint": {
        "ok": false,
        "findings": [
          { "sample_index": 1, "severity": "error", "pattern": "payday-loan", "suggestion": "Remove short-term lending language from the sample message." }
        ]
      }
    }
  },
  "meta": { "request_id": "req_4c1d8e2f", "timestamp": "2026-09-12T14:25:41Z" }
}

The recovery path is a lint-in-edit loop, not a resubmit-and-pray:

Read error.details.lint.findings — each entry names the sample, the pattern it matched, and a suggestion.
Fix the flagged sample messages (or narrow your use case if the traffic legitimately falls in a regulated vertical), then test the fixed samples against POST /api/v1/numbers/tfv-lint. That endpoint runs the same lint without submitting anything.
Once the lint returns ok: true, re-submit POST /api/v1/numbers/:id/tfv with the fixed samples.

`LOA_NOT_SIGNED` — hosted message order missing its LOA

Hosted messaging (“Hosted SMS”) text-enables a landline or a toll-free number that someone else owns the voice on: you keep the number’s voice traffic on its current carrier, and Orbit takes over the SMS. The mechanism is a Letter of Authorization (LOA) the carrier requires — and orders sit in a lifecycle: draft → loa_signed → submitted → active. The submit endpoint refuses to move an order that skipped the signature step:

{
  "error": {
    "code": "LOA_NOT_SIGNED",
    "status": 409,
    "message": "The LOA must be signed before the order can be submitted."
  },
  "meta": { "request_id": "req_7a0b4f91", "timestamp": "2026-09-12T14:31:02Z" }
}

The fix is the in-platform signature step, then re-submit:

curl -X POST \
  https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/<order-id>/loa/sign \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "signerName": "Alex Morgan", "signerEmail": "alex@example.com" }'

Then re-submit the order — the same POST /api/v1/numbers/hosted-messaging/<order-id>/submit call succeeds once loaSignedAt is stamped, and the order moves to submitted. The full lifecycle guide is at Hosted messaging.

What not to do

Do not retry the same send against a gate. Every one of these refuses deterministically before queue or carrier fan-out; a retry loop earns the same 422/409 and burns rate-limit budget on a decision your side must change anyway.
Do not drop the media and silently re-send the same MMS payload. MMS_NANP_ONLY names the recipient: cascade to SMS for that recipient, keep MMS on NANP, or route through a media-capable channel (RCS, WhatsApp) — but a verbatim re-send is just the same refusal again.
Do not treat NOT_SMS_CAPABLE as transient. It is in the permanent retry-suppression set by design: no retry will move the outcome, only a sender change will.
Do not re-submit an unchanged TFV filing. The carrier would have bounced the same samples the lint flagged; the lint’s judgement is the preview, not the problem.

Paste these into a support ticket

Pick from the block below when the fix above cannot land (a stuck TFV filing, a capability mismatch you cannot see on your Numbers page, an LOA that looks signed but still 409s):

Error code: <e.g. TFV_LINT_BLOCKED>
Endpoint: <e.g. POST /api/v1/numbers/:id/tfv>
request_id: <from error.meta.request_id>
Timestamp: <UTC, or local time with tz>
Number / asset: <E.164 or order id>
What you changed before the last attempt: <e.g. replaced sample 2>

US toll-free sender blocked with TFV_REQUIRED — the sibling gate on set-not-verified toll-free senders; the lint gate above in this page is the pre-submit sibling.
Hosted messaging guide — the LOA lifecycle end to end.
MMS media-rich content guide — the channel constraints MMS answers to.
Error Code Reference — the full catalog where these four codes sit.
FAQ — the short-form summary of this gate set.

​Troubleshooting: sender and asset preflight gates

​Match the channel, then the gate

​Per-code cause table

​MMS_NANP_ONLY — MMS outside North America

​NOT_SMS_CAPABLE — the sender cannot carry SMS

​TFV_LINT_BLOCKED — toll-free filing refused by the content lint

​LOA_NOT_SIGNED — hosted message order missing its LOA

​What not to do

​Paste these into a support ticket

​Related references

Troubleshooting: sender and asset preflight gates

Match the channel, then the gate

Per-code cause table

`MMS_NANP_ONLY` — MMS outside North America

`NOT_SMS_CAPABLE` — the sender cannot carry SMS

`TFV_LINT_BLOCKED` — toll-free filing refused by the content lint

`LOA_NOT_SIGNED` — hosted message order missing its LOA

What not to do

Paste these into a support ticket

Related references