twilio 21608 'the phone number is unverified' - agent dialing from a trial number outside the verified list

TL;DR

Read the error literally: it names the exact constraint you violated. Map the code to the field, quota, or permission it protects, fix the request to respect it, and add a pre-flight check so the agent stops sending requests the provider will reject.

The query

twilio 21608 'the phone number is unverified'  -  agent dialing from a trial number outside the verified list

Use this when

• a provider returns a named error code or a 4xx/5xx on a specific call
• the same call works for some records and fails for others

Not for

• timeouts with no response (see the timeout skill)
• webhook delivery problems (see the webhook skill)

Steps

Step 1: Quote the exact error and find its documented meaning

Copy the full error string, code included, into your notes and look it up in the provider's docs. Error codes are precise: 'invalid' vs 'missing' vs 'expired' point at different fixes. Do not paraphrase the error before diagnosing it.

**Expected: the documented meaning of the exact code, not a guess.

Step 2: Reproduce with the smallest possible request

Strip the failing call down to the minimum that still errors: one record, one field. This separates 'the payload is wrong' from 'the credential/quota/config is wrong' in one step.

**Expected: a minimal repro that fails the same way, or a minimal call that succeeds.

Step 3: Fix the request to respect the constraint

Missing field: add it. Invalid value: use an allowed one (check picklist/enum values live, not from memory). Quota: slow down. Permission: get the scope granted. Expired: refresh. Match the fix to the code's meaning from step 1.

**Expected: the minimal repro from step 2 now succeeds.

Step 4: Add a pre-flight check in the agent

Validate before the provider does: required fields present, enum values allowed, payload under size caps, credential fresh. Pre-flight checks turn provider 4xxs into caught exceptions with clear messages.

**Expected: the agent rejects bad requests locally with a message naming the problem.

Step 5: Log the code on every failure from now on

Structured logging of provider, code, and request id on every error. The next incident starts with the code already in the logs instead of a support ticket asking for it.

**Expected: error logs carry provider + code + request id; future diagnosis starts there.

Why it happens

Provider errors are the API telling you its rules: required fields, allowed values, quotas, permissions, and state preconditions. Agents that build requests from assumptions instead of checking the schema hit these on every edge case.

Edge cases

• Docs lag the API: when docs and behavior disagree, trust a probe, not the page.
• Some 4xxs are quota-shaped (429) or auth-shaped (401); treat those with their own skills.
• Bulk APIs fail per-item: always read the per-item error array, not just the top-level status.

Finding this skill

This skill was written for sales-outreach (SDR) agents hitting the failure above. Search Vectle for the exact error text or symptom to find it and related skills.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_BnDMjknHhuO93-LKNQPv9Q