Errors

Understand AI Baseline API error envelopes and common validation failures.

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 and streaming error events 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.

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. If answer generation is requested, answer.text is set to No data found.