Errors

Request failures return a JSON ErrorResponse envelope:

{
  "status_code": 422,
  "message": "Validation error",
  "detail": {
    "code": "FILTER_FIELD_UNKNOWN",
    "message": "unknown metadata filter field 'company'",
    "limit": ["sec_ticker", "sec_form_type"],
    "observed": "company"
  }
}

Request-body validation errors use the same envelope with a structured error list:

{
  "status_code": 422,
  "message": "Validation error",
  "detail": {
    "code": "VALIDATION_ERROR",
    "errors": [
      {
        "field": "include.unsupported",
        "code": "extra_forbidden",
        "message": "Extra inputs are not permitted"
      }
    ]
  }
}

Server failures include stable error codes, for example {"code": "INTERNAL_SERVER_ERROR"}.

Status Codes

Status	Meaning
`401` or `403`	The `X-API-Key` header is missing or invalid.
`404`	The requested endpoint is unavailable.
`413`	The raw request body is larger than `65,536` bytes.
`422`	Request validation failed.
`500`	The server hit an unexpected error.
`503`	A required runtime service is unavailable.

Common Validation Failures

Code or message	Cause
`QUERY_EMPTY`	The query is empty.
`QUERY_TOO_LONG`	The query exceeds `4,000` characters.
`REQUEST_TOO_LARGE`	The raw JSON body exceeds the request size limit.
`FILTER_FIELD_UNKNOWN`	A metadata filter names an unsupported field.
`FILTER_OPERATOR_UNSUPPORTED`	A metadata-filter field does not support the requested operator.
`FILTER_VALUE_TYPE_INVALID`	A metadata filter value has the wrong type for the field or operator.
`FILTER_VALUE_UNKNOWN`	A categorical value cannot be canonicalized to an allowed value.
`FILTER_EXPRESSION_UNSUPPORTED`	The request used expression-style metadata filters instead of the supported metadata filter format.
`extra_forbidden` for `filters`	Use `metadata_filters`; the legacy `filters` request key is rejected.

Successful Responses with Warnings

Partial retrieval and token-budget truncation are successful HTTP 200 responses. Inspect summary.warnings, coverage, and evidence_budget to decide whether to answer, retry with a larger budget, or report an evidence gap.

Warning	Meaning
`LOW_EVIDENCE`	Retrieval genuinely found no evidence.
`PARTIAL_EVIDENCE`	An `agentic_research` response did not cover every planned requirement.
`COVERAGE_NOT_ASSESSED`	Requirement decomposition failed and fallback retrieval was used.
`EVIDENCE_BUDGET_TRUNCATED`	One or more available complete evidence chains were omitted to satisfy `retrieval.max_evidence_tokens`.

When no evidence is found, the query still returns a successful response. summary.warnings includes LOW_EVIDENCE, and retrieval-derived sections such as metadata_distribution are empty when requested. An undersized token budget is different from an empty retrieval. If evidence was found but no complete chain fits, the API omits evidence, reports requirements as omitted_by_budget, and includes EVIDENCE_BUDGET_TRUNCATED. It does not return "No data found" or add LOW_EVIDENCE.

Get Started

Guides

API Reference

Status Codes

Common Validation Failures

Successful Responses with Warnings

​Status Codes

​Common Validation Failures

​Successful Responses with Warnings

Status Codes

Common Validation Failures

Successful Responses with Warnings