Errors

Overview

Lightcast MCP returns structured errors when a request cannot be processed successfully.

Errors can occur during request validation, tool execution, downstream service communication, or dependency health checks. Error responses are designed to help clients identify the cause of a failure and determine whether a request should be corrected, retried, or escalated.

Lightcast MCP uses a JSON error structure with stable application error codes.

Error Structure

An error object contains information about what failed and, when applicable, where the failure occurred.

Field	Description
`status`	HTTP-style status code as a string.
`code`	Stable Lightcast MCP error code.
`title`	Short error title.
`detail`	Human-readable detail.
`source.pointer`	Optional JSON pointer to the invalid input location.
`source.parameter`	Optional parameter reference.
`meta`	Optional structured metadata, such as allowed values or received value.

MCP Tool Error Behavior

Tool-level errors are returned inside the MCP tool result.

When a tool call fails:

isError is set to true
Error details are returned as MCP text content items
One or more JSON error objects describe the failure

Tool-level failures can be returned within a successful HTTP response. Clients should inspect the MCP tool result rather than relying solely on the HTTP status code.

Non-MCP endpoints, such as dependency health checks, may return traditional HTTP error responses with an { "errors": [...] } response body.

Error Categories

The following error codes are currently implemented.

Code	Status	Meaning
`VALIDATION_FAILED`	`400`	Tool input failed schema or adapter validation.
`INVALID_ARGUMENT`	`400`	A required high-level argument, such as `dataset`, is missing or malformed.
`TOOL_INVALID_COMBINATION`	`400`	The requested dataset/tool pair is not supported.
`TOOL_UNSUPPORTED_DATASET`	`400`	The dataset string is not an implemented dataset.
`DOWNSTREAM_REQUEST_FAILED`	`502`	A downstream request returned a non-OK response.
`DOWNSTREAM_BAD_RESPONSE`	`502`	A downstream response did not match the expected shape.
`DOWNSTREAM_UNAVAILABLE`	`503`	A downstream service was unavailable, returned a 5xx response, or had a network failure.
`DOWNSTREAM_AUTH_FAILED`	`500`	Downstream authentication failed after implemented retry behavior.
`DEPENDENCY_UNHEALTHY`	`503`	A dependency status check reported unhealthy.
`DEPENDENCY_CHECK_FAILED`	`503`	A dependency status check failed or rejected.
`UNEXPECTED_INTERNAL_ERROR`	`500`	An unknown runtime failure occurred.

Validation Errors

Validation errors occur before a request reaches a downstream service. These errors indicate that the request does not satisfy the selected dataset, tool contract, or schema requirements.

Common causes include:

Cause	Example
Unsupported dataset	`dataset` is not one of `job_postings` or `profiles`,
Unsupported tool combination	Calling `timeseries` with `profiles`.
Unsupported metric	Requesting a `profiles` metric from `job_postings`.
Invalid operator	Using `and` on a dimension that only supports `or`.
Missing required filter	Omitting `time` for a `job_postings` analysis request.
Invalid range	Supplying an upper bound lower than a lower bound.

Validation errors may include JSON pointers such as /filter/time or /metrics/0, along with metadata describing the expected values or structure.

Execution Errors

Execution errors occur after request validation succeeds. These failures are typically caused by downstream service responses, authentication issues, network failures, or dependency health problems.

Failure Type	Client Guidance
Downstream request failed	Review the request and returned error details.
Downstream bad response	Treat as a service-side response-shape issue.
Downstream unavailable	Retry may be appropriate, depending on the calling workflow.
Downstream auth failed	Treat as a service configuration or credential issue.

Retry Behavior

Some execution errors may be retried automatically depending on the downstream service and failure type.

Area	Behavior
OAuth tokens	Tokens are cached by scope and refreshed before expiry.
Downstream 401 responses	The server can invalidate the token and retry once.
Profiles 429 or 5xx responses	Profiles requests retry once, using `Retry-After` when available or a short exponential delay.
Job postings 429 or 5xx responses	No documented retry beyond returning downstream errors.
Government occupations 429 or 5xx responses	No documented retry beyond returning downstream errors.
MCP layer	No standardized MCP-layer retry contract is currently documented.