Troubleshoot Lookup per-field verdicts (200 with `coming_soon` / `not_implemented` / `error`)

The Full Intelligence endpoint (GET /api/v1/numbers/lookup/:phone) answers 200 whenever the base lookup succeeded — even when every fields= data package you asked for came back without a payload. Isolation is per field: the base lookup and each data package run independently, so a provider fault on one field does not blank the others. That means a 200 is not a guarantee of data. Read every dataPackages entry’s status before you treat the lookup as enriched.

{
  "data": { "phoneNumber": "+14155550100", "valid": true, "liveStatus": "yes" },
  "dataPackages": {
    "line_type_intelligence": { "status": "available", "provider": "devotel-hlr", "data": { "type": "mobile" } },
    "sim_swap": { "status": "coming_soon", "reason": "upstream_provider_not_contracted", "provider": "camara" },
    "identity_match": { "status": "error", "reason": "identity_attributes_required", "provider": "camara" }
  },
  "meta": { "request_id": "req_8f3…" }
}

1. Decode the status buckets

Each non-available status tells you a different thing:

Status	What it means	Your move
`coming_soon` (reason `upstream_provider_not_contracted`)	The field is in the catalog but the upstream provider is not configured for this deployment. For CAMARA-gated fields (`sim_swap`, `identity_match`) that means no CAMARA operator binding exists yet. Replaying will not change the answer until the vendor work lands.	Drop the field from enrichment, or ask support which provider contract activates it. Do not design integrations assuming a payload.
`not_implemented` (reason `vendor_integration_pending`)	No provider driver has been wired for this field yet (transient — a future release can flip it to `available` without a schema change).	Treat like `coming_soon` — no retry will help.
`error`	The provider call for this specific field failed. The base lookup may still have succeeded.	Fix request-shaped reasons yourself (see below); for genuine provider faults, retry the same request once after a short backoff, then escalate with the `request_id`.

The 502 LOOKUP_FAILED code (both providers down, or the fallback unreachable) is a different failure mode — the whole lookup failed, not just one field. That is handled in the Lookup and messaging-service failures runbook.

2. Map the field to its provider

Map the failing field to its provider before you conclude anything — only some fields can come back coming_soon, and each has a specific activation path:

Field	Provider	When it goes non-`available`
`line_type_intelligence`, `operator_name`, `phone_number_quality_score`	Devotel HLR (base lookup path)	Never `coming_soon` — when HLR is unconfigured the whole endpoint is unavailable, not just these fields.
`sim_swap`	CAMARA SIM Swap (GSMA Open Gateway), Telnyx Lookup v2 best-effort fallback	`coming_soon` when no CAMARA operator is configured for the deployment and the Telnyx fallback has no signal.
`identity_match`	CAMARA KYC Match (GSMA Open Gateway)	`coming_soon` until a CAMARA operator is configured. When CAMARA is reachable but you supplied no `identity_*` attribute, the field returns `error` with reason `identity_attributes_required` — fix the request, not the provider.
`caller_name`, `cnam`	Telnyx Lookup v2 caller-name dip	`coming_soon` only when the dip is not configured. A configured dip with no CNAM record returns `available` with `data.caller_name: null`.
`reassigned_number`	FCC Reassigned Numbers Database	`error` with reason `consent_date_required` when you omit `consent_date` — fix the request. `coming_soon` until the RND feed is provisioned.
`call_forwarding`, `live_activity`, `sms_pumping_risk`	Derived from the Devotel HLR reachability dip	`coming_soon` when the HLR dip returned no usable signal — retry the lookup once, then accept an unchanged answer as the “no data” signal.
`number_reputation`	Derived from HLR/Telnyx signals	`not_implemented` when no usable signal is present.

3. Retry or escalate?

Fix the request yourself: error with a request-shaped reason — identity_attributes_required on identity_match, or consent_date_required on reassigned_number. Send the missing attribute/date and the field returns real data.
Retry once, then escalate: error with a genuine provider rejection on a field that normally returns data. One retry is enough — a repeat failure points at the provider, not at your request.
Never retry: coming_soon and not_implemented. Replaying burns wallet without changing the answer.

4. Escalation bundle

When you open a support ticket, include:

The meta.request_id of the failed lookup.
The exact fields= selector you sent.
The per-field status buckets you received — each coming_soon, not_implemented, or error entry with its reason and provider strings.

That bundle lets support trace the exact upstream call that failed, or confirm which provider contract needs to land to unblock the field.

Number lookup and messaging-service failures — the 502 LOOKUP_FAILED and the MESSAGING_SERVICE_* resolution codes this page’s sibling runbook owns.
Number Lookup — the full data-packages catalog, the fields= selector contract, and the per-field status table.
Error codes reference — the wire surface the LOOKUP_FAILED code is registered on.

Reference

Troubleshoot Lookup per-field verdicts (200 with coming_soon/not_implemented/error)

Troubleshoot Lookup per-field verdicts (200 with `coming_soon` / `not_implemented` / `error`)

1. Decode the status buckets

2. Map the field to its provider

3. Retry or escalate?

4. Escalation bundle

​Troubleshoot Lookup per-field verdicts (200 with coming_soon / not_implemented / error)

​1. Decode the status buckets

​2. Map the field to its provider

​3. Retry or escalate?

​4. Escalation bundle

​Related references

Troubleshoot Lookup per-field verdicts (200 with `coming_soon` / `not_implemented` / `error`)

1. Decode the status buckets

2. Map the field to its provider

3. Retry or escalate?

4. Escalation bundle

Related references