unresolved_reference

A name or identifier in the request does not match anything.

HTTP status: 422 Unprocessable Entity

A parameter that identifies something — entity_id, company_id, podcast_id, episode_id, publisher_id, topic_id, or ticker — was supplied, but the value does not match any record. The response names the parameter and the value that failed. This holds on every endpoint that takes these filters, lists and timeseries alike. A list filter that takes several values names the first one that matched nothing.

A reference that matches something with nothing to show is different: a podcast with no clips, or a company with no sponsorships, returns an empty data array. So does a lookup filter on GET /v1/companies (ticker, domain, cik, qid): it asks which companies carry that identifier, and none is an answer.

The occupation and field parameters behave the same way: occupation, field, guest_occupation, guest_field, and parent on the occupation and field lists, wherever they appear (the expert search, the guest directory, the episode, search and mention filters, and the podcast list’s guest filters). For these, the detail also offers up to three of the closest codes, such as Did you mean Cardiologists (29-1212, cardiologists)?, so a caller can often retry without another lookup. On the MCP server the same error names particle_expertise_resolve as the tool to call.

person_id is not in that list. It is a real filter on the episode endpoints, but an unresolvable one returns an empty page rather than this error, so do not build a handler for unresolved_reference on it.

The request is rejected rather than answered, because an empty result set would be indistinguishable from “we have no content about this”, and would send you looking for the wrong problem.

Example

{
  "type": "https://docs.particle.pro/errors/unresolved_reference",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "company_id 'x' did not match any company.",
  "error_code": "unresolved_reference",
  "resolve": {
    "message": "Resolve the name to a slug first, then filter on the slug.",
    "action": "resolve_reference",
    "method": "GET",
    "endpoint": "/v1/companies?q=x"
  }
}

How to fix

1. Call the matching search endpoint with the name as free text — /v1/companies?q=… for companies, /v1/entities/search?q=… for entities, people, and tickers, /v1/podcasts/search?q=… for shows, /v1/podcasts/publishers?q=… for publishers, /v1/people/occupations?q=… for occupations and /v1/people/fields?q=… for fields of research. Episode slugs are not searched by name: list a podcast’s episodes with /v1/podcasts/episodes?podcast_id=…. Topics are not searched by name either: browse the tree from /v1/topics.
2. Take the slug from the top result.
3. Re-issue the original request with that slug.

The resolve.endpoint field on the error already carries the correct call for the parameter that failed, so an automated caller can follow it directly rather than choosing from this list.

Slugs returned by any endpoint are stable and accepted everywhere the corresponding identifier is, so resolve once and reuse the slug across calls.

Passing a name where a slug is expected is the most common cause. company_id accepts a slug, a domain, or an internal ID — but not a display name.