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

# AI Search API Errors

> Error codes returned by the AI Search Collections API and how to resolve them.

AI Search returns failures in the standard Telnyx **plural error envelope** -- branch on `errors[].code` and read `detail`.

The code style depends on the **operation**:

* **Collection management** (create, retrieve, update, delete, the sources subresource, and the settings subresource) is **mixed**: its specific failures use **string codes** -- for example `collection_not_found`, `collection_slug_taken`, `source_already_exists`, `invalid_source_type`, `invalid_top_k` (often with a `meta.pointer`) -- while the **shared** malformed (`10015`) and auth (`10009`) failures use the general **numeric** codes.
* **Search** (the documents endpoint) uses **general numeric codes** -- `10005`, `10027`, `10015` -- each with a `meta.url` link.

Authentication is shared: a missing or invalid API key returns `401` with `10009` (see the [general API error codes](https://developers.telnyx.com/docs/development/api-fundamentals/api-errors.md)); authenticated requests may also see `403`, `429` (with `Retry-After`), or `503`.

Branch on `code` and read `detail` -- don't assume a numeric or string shape: collection management **mixes** string codes (its specific cases) with the shared numeric `10015` / `10009`, and search is numeric throughout.

**Not every failure uses the JSON envelope.** A couple of framework-level rejections bypass the error handler: an **unknown key** in a settings request returns a raw `400` as `text/plain` (not `{"errors":[...]}`), and a wrong `Content-Type` returns a bare `415` with an empty body. Check the response status and `Content-Type` before parsing `errors[]`.

## Collection management errors

Returned by create / retrieve / update / delete, the sources subresource, and the settings subresource.

| Code | HTTP | When | Action |
| - | - | - | - |
| `collection_not_found` | `404` | No collection with that `uuid` / `slug` for the account. | Verify the id and that it belongs to this account. |
| `source_not_found` | `404` | On the sources subresource, no source with that id on the collection. | List the collection's sources and use an existing id. |
| `collection_slug_taken` | `409` | On create, a collection with that `slug` already exists for the account. | Choose a unique `slug`. |
| `source_already_exists` | `409` | The same source appears twice -- on create, or when adding or replacing sources: the same `source_type` (and, for `bucket`, the same `bucket_id`). | Remove the existing source or attach a different one. |
| `name_required` | `422` | `name` is missing or blank on create. | Send a non-empty `name`. |
| `reserved_collection_slug` | `422` | The `slug` -- or the slug derived from `name` when none is sent -- is reserved. | Send a different `slug` or `name`. |
| `invalid_source_configuration` | `422` | A `bucket` source is missing its `bucket_id` (see `meta.pointer`). | Supply `bucket_id` for each bucket source. |
| `invalid_source_type` | `422` | A `source_type` outside the `SourceType` enum. | Use `voice`, `email`, `whatsapp`, `meeting_bot`, `message`, or `bucket`. All are searchable today except `bucket` (coming soon). |
| `unsupported_retrieval_type` | `422` | `retrieval_type` is not `vector` or `hybrid` -- e.g. `keyword` (coming soon). | Set `vector`; see [Search Modes](https://developers.telnyx.com/docs/ai-search/search-modes.md). |
| `invalid_top_k` | `422` | `top_k` is outside `1--50`. | Use an integer in `1--50`. |
| `10015` | `400` | Malformed request or failed validation. | Correct the request per `detail`. |
| `10009` | `401` | Missing or invalid authentication. | Send your Telnyx API key as a bearer token. |

```json theme={null}
// 409 -- slug already in use (string code, with meta.pointer)
{
  "errors": [{
    "code": "collection_slug_taken",
    "title": "Collection slug already in use",
    "detail": "A collection with slug 'support-transcripts' already exists for this account.",
    "meta": { "pointer": "/slug" }
  }]
}
```

## Search errors

Returned by the documents (search) endpoint -- general numeric codes with a `meta.url`.

| Code | HTTP | When | Action |
| - | - | - | - |
| `10005` | `404` | No collection with that `slug` for the account. | Verify the `slug`. |
| `10027` | `422` | The collection has no searchable sources. | Attach a searchable source before querying. |
| `10015` | `400` | Malformed request -- for example filtering on a non-filterable field such as `region` or `score`. | Correct the parameter named in `detail`. |
| `409` | `409` | The collection's `retrieval_type` is `hybrid`, but hybrid search is not enabled yet. | Set `retrieval_type` to `vector`; see [Search Modes](https://developers.telnyx.com/docs/ai-search/search-modes.md). |
| `503` | `503` | The collection configuration or the search backend is temporarily unavailable. | Retry with backoff. |

```json theme={null}
// 422 -- collection has no searchable sources (numeric code, with meta.url)
{
  "errors": [{
    "code": "10027",
    "title": "Unprocessable Entity",
    "detail": "The server understood the syntax of the request but was unable to process the instructions.",
    "meta": { "url": "https://developers.telnyx.com/docs/overview/errors/10027" }
  }]
}
```

## Related

* [Search](https://developers.telnyx.com/docs/ai-search/searching.md) -- the retrieval call and its parameters
* [Settings](https://developers.telnyx.com/docs/ai-search/settings.md) -- `retrieval_type` and `top_k` validation
* [Collections](https://developers.telnyx.com/docs/ai-search/manage-collections.md) -- create, list, retrieve, update, delete
* [General API errors](https://developers.telnyx.com/docs/development/api-fundamentals/api-errors.md) -- the shared pre-service error codes