> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-baseline.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Understand AI Baseline API error envelopes and common validation failures.

Request failures return a JSON `ErrorResponse` envelope:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`.