Error Reference — Comscore MCP Developer Reference

Base result fields

Every tool response includes these fields from the base result type. On success, error and error_code are null. On failure, error is always populated and error_code carries a stable machine-readable identifier.

Field	Type	Description
error	string \| null	Human-readable failure message. Set only on failure; `null` on success.
warning	string \| null	Recoverable failure message. Includes retry guidance when relevant. May be set alongside a partial result.
error_code	string \| null	Stable machine-readable code. Use this for programmatic handling — the `error` text is for humans and may change. `null` on success.
retryable	boolean \| null	`true` when the same call is worth retrying unchanged — indicates a transport or timing failure, not a request error. `false` or `null` means the request itself is the problem.

Error codes

The following error_code values are stable across releases. All other text in error responses is human-readable and may change.

access_denied

Your account is not subscribed to the requested data. The request was valid but your entitlements do not cover it. Not retryable. Contact your Comscore account manager to add the relevant product to your subscription.

upstream_timeout

The Comscore data connector timed out waiting for a response. This says nothing about whether the underlying data is available — it is a transient timing failure. Retryable (retryable: true). Retry the same call unchanged.

upstream_unavailable

The MCP server could not reach the upstream Comscore API. This is a transient infrastructure issue. Retryable (retryable: true). Retry after a short delay.

upstream_error

The upstream Comscore API rejected the request. The error field includes the API's response for diagnosis. May or may not be retryable depending on context — check the retryable field.

invalid_request

The arguments or their combination are not supported. The error message names a supported alternative when one exists. Not retryable without changing the request. Fix the parameters before retrying.

report_failed

The report was accepted by the upstream API but produced no data within the allowed time. This can indicate a data availability gap for the requested period, market, or metric. Check the retryable field; if true, the same call may succeed on retry.

Social-specific fields

Social tools that accept batches of entity names include additional fields on the _NamedEntityResult base type for partial resolution failures.

Field	Type	Description
unresolved_names	array \| null	Names that could not be resolved to a unique entity, with candidates to try. Retry these calls with the specific candidate IDs rather than the original names.
resolved_names	array \| null	Names that resolved successfully, with their entity IDs. Use these IDs directly on retry rather than re-resolving by name.

When a batch request partially resolves — some names succeed, some fail — the result includes data for the resolved names and populates unresolved_names for the failures. Inspect resolved_names to extract the IDs for the entities that did resolve, then issue a second call using those IDs for the names that did not.