AI Search API Errors

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); 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.
`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.

// 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.
`503`	`503`	The collection configuration or the search backend is temporarily unavailable.	Retry with backoff.

// 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" }
  }]
}

Search — the retrieval call and its parameters
Settings — retrieval_type and top_k validation
Collections — create, list, retrieve, update, delete
General API errors — the shared pre-service error codes

AI Search

Concepts

Configuration

API

For AI Agents

AI Search API Errors

Collection management errors

Search errors

​Collection management errors

​Search errors

​Related

Collection management errors

Search errors

Related