Errors & retries
Check both the HTTP response and the operation’s status.
| Status | What to do |
|---|---|
| 400 | Check the request fields and E.164 number format. |
| 401 | Check the bearer credential. Do not retry with the same invalid credential. |
| 404 | For research create, there may be no person match. For a snapshot, check the run ID. |
| 502 | An upstream request failed. Inspect the error and operation before deciding whether a retry is safe. |
| 503 | The requested capability is not configured or available. Contact us during your pilot. |
HTTP 200 with no consolidated profile
/enrich-with-llm can return useful raw outcomes even when the LLM cannot produce a profile. llm.status can be completed, skipped, or error. NoPersonCandidates means no candidate person records were available for consolidation.
Do not treat a non-null HTTP body as a successful person match. Inspect consolidation?.profile and the lookup outcomes.
Timeouts
Consolidated enrichment can take longer than a single-source request. Set a client timeout that accommodates the service and handle cancellation without immediately repeating paid work.
Research create retries
Do not automatically retry a failed or timed-out POST /research. A response carrying mayHaveStarted: true means execution may already be underway. If you have a run ID, read that snapshot instead.