Carrier Lookup Timeout Recovery Without Partial Results
A practical guide to carrier lookup timeout recovery without partial results, with documented request boundaries and review steps for data teams.
Carrier lookup timeout recovery begins by separating a completed lookup from an uncertain transport event.
Carrier lookup timeout recovery begins by separating a completed lookup from an uncertain transport event. A synchronous single check may end without a normal result; a timed-out synchronous multi request fails as one request and does not return partial rows. Keep the original submitted identifiers and attempt state for review, then retry only under an explicit customer policy. Never fill missing carrier fields with guesses or label a timeout as “no carrier.”
Identify which stage actually failed
The Original Carrier Lookup provides the carrier to which a number range was originally allocated, number type and allocation geography. A completed response can contain empty carrier fields, which means those values were unavailable in that completed lookup. That is different from a service timeout, a rejected E.164 format or a client connection failure. A recovery procedure should classify the stage before deciding whether to send another request.
Start with the customer's own attempt record: request mode, submitted canonical number or ordered numbers, time sent, whether a response was received, and whether the application parsed it. These are proposed application-owned diagnostics, not a provider response schema. Protect full identifiers and credentials according to the organization's logging policy. The public API accepts a plus-prefixed E.164 number for realtime checks; a formatting rejection should go back to preparation, not into a timeout retry loop.
For a single request, distinguish a documented completed response from an undetermined service outcome and from no response observed by the client. The team should not assume a client-side timer proves what the server did. The API documentation is the authority for exact business codes and timeout behavior.
Use a failure-state table
A compact decision table keeps operational labels consistent. The actions below are customer-side recommendations; they do not claim automatic CarrierLookup retry behavior.
| Observed state | Interpretation | Next action |
|---|---|---|
| Completed response with carrier context | Normal result for original allocation | Store with source and check time |
| Completed response with empty carrier fields | Completed lookup with unavailable values | Preserve empty values; review if needed |
| Rejected E.164 input | Request did not meet input format | Correct the input before any new call |
| Undetermined service outcome | No normal carrier conclusion | Follow the team's explicit retry or review rule |
| Client transport timeout | Completion may be unknown locally | Preserve attempt and avoid claiming a result |
| Multi request timeout | Whole multi request failed, no partial rows | Keep all submitted identifiers together for recovery |
The table deliberately avoids “invalid number” as a default interpretation of a missing carrier. CarrierLookup is not a number-validity or reachability product. An undetermined or failed check should remain separate from a completed lookup, even when the user interface has space for only one status badge.
Recover a multi request as a unit
Synchronous multi checks take an ordered list of E.164 numbers in one request. The documented multi timeout fails the whole request without partial results and returns the full amount. A client must therefore not infer that the first portion succeeded because a progress indicator moved or because a previous call with similar identifiers had results. Retain the exact ordered input and the attempt outcome. If the customer policy permits a retry, create a new attempt tied to the same job and reconcile the complete returned list only after that new response arrives.
If a normal multi response is received, reconcile the reported totals and ordered results before updating contact records. Individual exists=false entries indicate no normal result for that position, not proof of an invalid, disconnected or carrierless number. Do not copy that flag into a bulk CSV interpretation; bulk file output uses its own contract. Preserve per-item status independently from the carrier fields.
The application should also protect against stale writes. If a contact's phone number changed while the request was in flight, compare the submitted value with the current record before applying any result. A timeout recovery path should not bypass the same integrity check used for an ordinary successful response.
Define a retry policy around evidence and cost
A retry is a new lookup attempt, not a repair of missing values in an old response. Define which states are eligible, how many attempts the customer application permits, and who reviews persistent uncertainty. Those are application choices; do not describe them as undocumented provider limits or guarantees. Avoid immediate parallel retries that compete for the account's shared realtime slots. The public API documents concurrency controls, so retries should pass through the same queue as new work.
A completed code-zero result with all carrier fields empty can still be charged. Failed or undetermined lookups do not keep a charge under the documented billing facts. That distinction is useful for operational reconciliation, but this article does not quote an amount or turn a technical timeout into a purchase-refund promise. Billing state and result meaning should be reviewed separately.
After an incident, sample the attempt log for three errors: timeouts presented as empty carrier results, multi requests treated as partial successes, and retries applied to contacts whose number changed. Correct the mapping and replay only cases the team's policy allows. The outcome of a sound recovery process is an honest evidence trail, not a claim that every number will eventually yield a carrier value.
Keep the customer-facing status language as careful as the internal state. “We could not complete the check” is different from “no carrier was found.” A reviewer should be able to trace that status back to the attempt record, understand whether a new attempt occurred, and see which result, if any, was ultimately used. This small discipline prevents a transport incident from becoming a false data-quality conclusion in the CRM.
FAQ
Does a multi timeout return partial carrier results?
No. The documented synchronous multi timeout fails the whole request without partial results.
Is an empty carrier field the same as a timeout?
No. A completed lookup may have unavailable carrier fields and still be a completed, chargeable result.
What should teams retain before retrying?
Keep the submitted canonical identifiers, mode, attempt time and observed failure state, then apply an explicit customer retry policy.
Can a timeout prove a phone number has no carrier?
No. It provides no normal carrier conclusion, and a carrier lookup does not establish number validity or reachability.
Learn More
Choose the product information that fits the next step in your workflow.