Errors

Application validation 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"
      }
    ]
  }
}

Execution failures use RequestFailureResponse: status_code, a safe message, and detail containing code and retryable. Optional reason and retry_after_seconds explain bounded capacity backoff. Codes include CAPACITY_UNAVAILABLE, DEPENDENCY_UNAVAILABLE, SERVICE_UNAVAILABLE, INVALID_UPSTREAM_RESPONSE, EXECUTION_DEADLINE_EXCEEDED, EXECUTION_WORK_LIMIT_EXCEEDED, and INTERNAL_SERVER_ERROR. Respect the returned retryability and delay; do not display raw internal diagnostics.

Gateway errors

An unsupported API version or unmatched public URL returns HTTP 404 with {"error_msg":"404 Route Not Found"}. No alternative version is selected. Authentication failures use the gateway’s { "error": "invalid_api_key" } or { "error": "access_denied" } shape. Quota failures return HTTP 429 with detail.code=RATE_LIMIT_EXCEEDED and a Retry-After header. These gateway responses are separate from application validation/execution envelopes.

Status Codes

Status	Meaning
`401` or `403`	Authentication failed or the credential does not grant access to the selected knowledge base.
`404`	The requested endpoint is unavailable.
`413`	The raw request body is larger than `65,536` bytes.
`422`	Request validation failed.
`429`	Consumer quota exceeded; honor `Retry-After`.
`500`	The server hit an unexpected error.
`502`	A required upstream response was invalid. Inspect the returned retryability.
`503`	A required runtime service is unavailable.
`504`	Query execution exceeded its deadline. Narrow the query or retry as indicated.

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.

Citation links

Unknown, malformed or expired links and unavailable retained content disclose no private source details. Request a fresh link through authorized retrieval; do not construct or renew a URL. See citation availability and expiry.

Get Started

Connect

Guides

API Reference

Gateway errors

Status Codes

Common Validation Failures

Successful Responses with Warnings

Citation links

​Gateway errors

​Status Codes

​Common Validation Failures

​Successful Responses with Warnings

​Citation links

Gateway errors

Status Codes

Common Validation Failures

Successful Responses with Warnings

Citation links