Troubleshooting
Distinguish connection issues, missing inputs, no matches, and provider failures.
The agent cannot connect
A signed-in website session does not complete MCP authorization for your agent. In Claude Code, open /mcp and finish the PeopleRouter sign-in flow. If the server is missing, follow the Claude Code guide.
For clients configured with an API key, check that the key is still valid in API keys. Keep credentials out of prompts and screenshots when sharing an error.
Read the outcome
For capability calls such as people_search, check outcome before interpreting the returned data:
| Outcome | Meaning and next step |
|---|---|
hit | A provider returned the required result shape. Review the source and matching evidence. |
miss | The attempted search did not return a match. Check the identifier or adjust the search; this does not prove the person does not exist. |
needs_identifier | The input cannot identify the subject. Read error.message for an accepted combination, such as a profile URL or name plus company domain. |
error | The call failed. Read error.code, error.message, and error.hint; do not treat it as an empty search. |
Handle common errors
bad_input: correct the parameters using the current tool schema orendpointdetails before retrying.insufficient_credits: check the account balance in Overview.missing_credentialorcredential_rejected: the server's provider credential is unavailable or rejected. This differs from your own MCP sign-in failing; changing your PeopleRouter API key will not fix the provider's credential.rate_limited,timeout, orprovider_error: inspect_dinq.triedto see what has already been attempted before retrying or choosing another available provider.
Results are incomplete
Ask the agent to check whether the provider accepted all requested filters and whether a more precise profile URL would improve identification. Missing fields should remain unknown. For routed calls, inspect skipped attempts: the credit ceiling or provider preferences may have limited the search.
Before repeating a call, check Activity and the billing rules. Do not assume a repeated request is free. When reporting an issue, include the tool name, error code, approximate time, and relevant attempt details with credentials and personal data removed.