Skip to main content
This page contains reference material to assist you with troubleshooting Twilio rejection reasons, error codes, and good practices (opt-in collection, double opt-in, STOP/HELP handling) that affect whether your submission gets approved in the first place.

Approval Patterns

How to design your messaging program so it passes carrier review.

Common Rejection Reasons

The exact text strings Twilio returns and how to fix each.

Error Code Reference

The numeric 30xxx codes you’ll see in failureReason.

​
Approval Patterns

Gathering user opt-in consent is the most critical portion of the approval flow. There are a few ways to gather user consent that are approved by Twilio:
A checkbox next to a phone field. The form discloses what the recipient will receive, who’s sending, that msg & data rates apply, and how to opt out. The checkbox must not be pre-checked. You retain a record (timestamp, IP, form version).
Single-source rule of thumb: if you can’t show a Twilio reviewer where consent was collected (URL of the form, photo of the in-person clipboard, or the inbound JOIN text), don’t include those contacts in your audience.

​
Opt-In Strategies

After the recipient consents via your collection source, VIVI’s consent middleware sends a confirmation message (“Reply YES to confirm you want to receive…”). The recipient must reply YES (or START) before they’re marked OPTED_IN. This is the default VIVI behavior.

Why?

Pre-empts disputes (“I never signed up”), reduces complaint rates, and is required for marketing campaigns in some jurisdictions.

How to Format

One extra reply at the start of the conversation. Most users do it.

Fallback

If the user never replies, the conversation never happens. The middleware queues your agent’s first message until consent lands — nothing is lost on your side, but the user-side opt-in might just never occur.

​
STOP and HELP

Every CTIA-compliant SMS program must respond to:

STOP

Aliases: UNSUBSCRIBE, END, CANCEL, QUIT — immediate opt-out.

HELP

Alias: INFO — return identifying information about the program and how to contact support.
VIVI handles this automatically via the consent middleware. The opt-out and help-response templates you configured in the SMS channel setup are what get sent. Your agent does not see STOP/HELP messages — the middleware intercepts them.

​
Re-Engagement After STOP

Once a user has texted STOP, you cannot legally text them again for that program — even if a year passes. The only way they can re-enter the program is to text START or YES themselves, which flips them to OPTED_IN and triggers the resubscribe confirmation template.You cannot “convert” a STOPped user back via your web form, even if they fill it out again.

​
Best Practices Summary

A summary that passes review hits four points:
1

Who is sending?

Your brand name.
2

Who is receiving?

A specific audience, not “the public”. E.g. “the franchise’s own staff and on-call technicians”.
3

What kind of message?

Transactional / customer care / 2FA / etc., explicitly named.
4

How consent was collected?

The source of consent, i.e. “Recipients opt in by texting JOIN to our number.” or “Recipients opt in on our online intake form.”
Add the following template to make unsubsciption clear: msg & data rates may apply, STOP to unsubscribe, HELP for help.
KSG operates the VIVI messaging platform for a restoration franchise. When the franchise’s 24/7 line logs an emergency restoration job, KSG texts the franchise’s staff and on-call technicians from this toll-free number that a dispatch is ready. Recipients reply OK to confirm; unacknowledged alerts re-send until confirmed. Internal transactional dispatch alerts only — no marketing. Technicians opt in by texting to join. Reply STOP to opt out, HELP for help.

​
Sample Messages

The sample messages field on A2P campaigns and the production message sample field on TFV both require a realistic example of what your agent will send in production, not a template or placeholder.
Carriers and Twilio reviewers will flag a sample that contains [brackets] as “template-style” and reject the submission.

​
Common Rejection Reasons

These are the exact strings you’ll see in failureReason (or, for live channels, in the rejection banner on the form), grouped by what VIVI receives back from Twilio.
Where you see it: Toll-free verification rejection banner.
  1. Length over 500 characters. Twilio’s hard length cap. The VIVI form now blocks typing past 500 with a live counter; if you’re seeing this error from a pre-existing submission, the row has stale data over cap. Open the form, shorten it, and save.
  2. Summary doesn’t match useCaseCategories. Categories say TWO_FACTOR_AUTHENTICATION but the summary describes appointment reminders, or vice versa.
  3. URLs, emails, or phone numbers in the summary. Put URLs in business_website / privacy_policy_url. Don’t put a contact phone in the summary.
  4. Marketing language on a non-MARKETING category. Words like “promotions”, “offers”, “deals”, “sale” combined with ACCOUNT_NOTIFICATIONS or 2FA triggers it.
  5. Placeholder text — “test”, “TBD”, “N/A”, a category name copied verbatim.
  6. Prohibited content keywords — cannabis, CBD, firearms, gambling, payday/debt collection in the content.
Fix: rewrite using the example pattern above.
Where you see it: Backend log error. VIVI catches this and prevents it from reaching the user.Root cause: the form was saved while a TFV is already on file for this phone number’s SID. Twilio enforces one active verification per phone number SID.VIVI’s behavior: the backend pre-flights Twilio’s status before submitting:
  • If the existing verification is PENDING_REVIEW / DRAFT / TWILIO_REJECTED → VIVI patches it with the new values (preserves audit trail).
  • If it’s IN_REVIEW / TWILIO_APPROVED → VIVI blocks the save with a clear 409 and a “fields locked” toast.
  • If a race produces this error despite the pre-flight, VIVI recovers by refreshing from Twilio’s truth instead of writing a spurious local “failed” state.
If you see this in old logs, those rows will self-heal on the next save.
Root cause: the physical address on the brand or TFV form failed Twilio’s address validator. Usually:
  • PO box (not allowed for brand or TFV business address).
  • Typo in street name.
  • Mismatched ZIP / state (e.g. 94105 paired with CA is fine, but 94105 paired with TX is rejected).
  • Building / suite number stuck on the street line without a separator.
Fix: copy the address from a USPS lookup or Google Maps and paste in. Use the address line 2 field for suite/apartment.
Root cause: the IRS database doesn’t show your EIN as active, or the legal name doesn’t exactly match what’s on file with the IRS.Fix:
  • Verify the EIN at the IRS’s EIN online verification.
  • The legal name field must match the EIN paperwork exactly — including LLC/Inc/Corp suffixes and capitalisation. If your IRS letter says “Acme Restoration LLC”, Acme Restoration (no LLC) will fail.
Root cause: you pasted a sample such as [Hi [Name], your appointment is at [Time]. Carriers reject samples with [bracketed] placeholders.Fix: render the placeholders before pasting. Submit a realistic example with real names and times.
Where you see it: A2P campaign row flips to FAILED and the failureReason field shows a carrier-supplied reason (often vague — “did not meet messaging guidelines”).Common root causes:
  • Use case category mismatch — you picked CUSTOMER_CARE but the sample messages look like marketing.
  • Insufficient opt-in evidence — the opt-in description doesn’t name the consent source.
  • Embedded links to an unverified domain — your privacy policy URL points at a domain different from your business website with no clear connection.
Fix: read the carrier reason carefully (which carrier? AT&T, T-Mobile, Verizon have different sensitivities), revise the relevant fields, click Resubmit. VIVI patches the existing campaign; you don’t lose your slot.

​
Error Code Reference

Twilio surfaces numeric error codes for SMS-platform errors. The most common ones you’ll see in VIVI’s logs or rejection banners:

​
Reading a Twilio Rejection in Detail

When a TFV is rejected, the failureReason field on toll_free_channel_compliance will look something like:
1

Numeric code

30445 maps to the Twilio docs URL: https://www.twilio.com/docs/api/errors/30445.
2

Rejection reason category

Use Case Information / Message Volume tells you which form section to focus on.
3

Specific note

“estimated monthly volume does not match…” is the actual feedback. This is what you act on.

​
When to Escalate

Most rejections are self-serve — fix the form, resubmit, wait. Escalate to Twilio support directly when:

Stalled review

A campaign or TFV has been in IN_REVIEW for more than 5 business days with no movement.

Permanent carrier failure on an approved number

You’re getting 30037 (Permanent carrier failure) on a verified, A2P-approved number — only Twilio can negotiate with the carrier.

Suspected throughput throttling

You suspect your brand trust score is artificially low and your throughput is throttled. Brand trust appeals go through Twilio support.

SMS Channel Creation

The channel-level flow that triggers compliance.

Compliance Hub Overview

Where you submit and track A2P and TFV registrations.