---
title: API error codes
description: Troubleshoot API and public endpoint errors.
image: https://developers.cloudflare.com/dev-products-preview.png
---

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

[Skip to content](#%5Ftop) 

# API error codes

When a request to the AI Search API or a public endpoint fails, it returns one of the errors documented on this page.

Errors that occur while an item is indexing are handled separately. See [Indexing error codes](https://developers.cloudflare.com/ai-search/troubleshooting/indexing-error-codes/).

## How errors are returned

The REST API and public endpoints return errors in a JSON envelope:

```json
{
  "success": false,
  "errors": [
    {
      "code": 7002,
      "message": "ai_search_not_found"
    }
  ],
  "result": {}
}
```

The [Workers binding](https://developers.cloudflare.com/ai-search/api/search/workers-binding/) throws exceptions. The exception `message` contains the AI Search error message, such as `ai_search_not_found`.

For Workers binding calls, the thrown error class depends on the upstream HTTP status:

| HTTP status | Workers binding error |
| ----------- | --------------------- |
| 404         | AiSearchNotFoundError |
| 5xx         | AiSearchInternalError |
| Other       | AiSearchError         |

## Common errors

These errors can occur across most AI Search API paths.

| Code  | Message                             | HTTP status | Details                                             | Recommended action                                                                                                                                                                                      |
| ----- | ----------------------------------- | ----------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 10000 | Authentication error                | 401         | Authentication failed.                              | Check your [API token](https://developers.cloudflare.com/ai-search/get-started/api/#1-create-an-api-token) and AI Search permissions.                                                                   |
| 7001  | Internal Error                      | 500         | An internal error occurred.                         | Retry the request. Check [Cloudflare Status ↗](https://www.cloudflarestatus.com) and [contact support](https://developers.cloudflare.com/support/contacting-cloudflare-support/) if the error persists. |
| 7002  | ai\_search\_not\_found              | 404         | The requested instance does not exist.              | Check the instance name and namespace.                                                                                                                                                                  |
| 7017  | unable\_to\_connect\_to\_ai\_search | 503         | AI Search could not connect to an internal service. | Retry the request. Check [Cloudflare Status ↗](https://www.cloudflarestatus.com) and [contact support](https://developers.cloudflare.com/support/contacting-cloudflare-support/) if the error persists. |
| 7063  | namespace\_not\_found               | 404         | The requested namespace does not exist.             | Check the [namespace](https://developers.cloudflare.com/ai-search/concepts/namespaces/) name.                                                                                                           |
| 7068  | Internal Error                      | 500         | An internal invariant failed.                       | Retry the request. Check [Cloudflare Status ↗](https://www.cloudflarestatus.com) and [contact support](https://developers.cloudflare.com/support/contacting-cloudflare-support/) if the error persists. |

## Instances

These errors can occur when you create, read, update, delete, or get stats for AI Search instances through the REST API or Workers binding.

| Code | Message                                                         | HTTP status | Details                                                                             | Recommended action                                                                                                                                                                                                                              |
| ---- | --------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 7002 | ai\_search\_not\_found                                          | 404         | The requested instance does not exist.                                              | Check the instance name and namespace.                                                                                                                                                                                                          |
| 7017 | unable\_to\_connect\_to\_ai\_search                             | 503         | AI Search could not connect to the indexing engine.                                 | Retry the request. Check [Cloudflare Status ↗](https://www.cloudflarestatus.com) and [contact support](https://developers.cloudflare.com/support/contacting-cloudflare-support/) if the error persists.                                         |
| 7010 | invalid\_model                                                  | 400         | The configured or requested model is invalid.                                       | Use a [supported model](https://developers.cloudflare.com/ai-search/configuration/models/supported-models/).                                                                                                                                    |
| 7018 | ai\_gateway\_not\_found                                         | 400         | The AI Gateway configured for the instance was not found.                           | Set ai\_gateway\_id to an existing gateway when you [create or update the instance](https://developers.cloudflare.com/ai-search/api/instances/rest-api/), or create the gateway in [AI Gateway](https://developers.cloudflare.com/ai-gateway/). |
| 7012 | ai\_search\_instance\_invalid\_token                            | 400         | The service API token configured for the instance is invalid.                       | Create or update the [service API token](https://developers.cloudflare.com/ai-search/configuration/indexing/service-api-token/) used by the instance.                                                                                           |
| 7013 | max\_instances\_reached                                         | 403         | The account reached its instance limit.                                             | Delete unused instances or [request a higher limit](https://developers.cloudflare.com/ai-search/platform/limits-pricing/#limits).                                                                                                               |
| 7022 | ai\_search\_with\_this\_name\_already\_exist                    | 400         | An instance with this name already exists in the namespace.                         | Use a different instance name or [namespace](https://developers.cloudflare.com/ai-search/concepts/namespaces/).                                                                                                                                 |
| 7023 | domain\_not\_owned\_by\_user                                    | 400         | AI Search could not confirm ownership of a website data source domain.              | Check that the domain is [onboarded to Cloudflare](https://developers.cloudflare.com/fundamentals/manage-domains/add-site/).                                                                                                                    |
| 7024 | invalid\_domain                                                 | 400         | The website data source domain is invalid.                                          | Check the [website data source](https://developers.cloudflare.com/ai-search/configuration/data-source/website/) URL.                                                                                                                            |
| 7028 | missing\_sitemap                                                | 400         | AI Search could not find a valid sitemap for the website data source.               | Add or update the website [sitemap](https://developers.cloudflare.com/ai-search/configuration/data-source/website/#sitemap).                                                                                                                    |
| 7029 | missing\_robots\_txt                                            | 400         | AI Search could not fetch robots.txt for the website data source.                   | Add a valid [robots.txt](https://developers.cloudflare.com/ai-search/configuration/data-source/website/#robotstxt) file with sitemap information.                                                                                               |
| 7034 | forbidden\_robots\_txt                                          | 400         | robots.txt blocks AI Search from crawling the website data source.                  | Allow the [AI Search crawler](https://developers.cloudflare.com/ai-search/configuration/data-source/website/#robotstxt) to crawl the site.                                                                                                      |
| 7035 | forbidden\_sitemap                                              | 400         | AI Search cannot access the website data source sitemap.                            | Allow the AI Search crawler to access the [sitemap URL](https://developers.cloudflare.com/ai-search/configuration/data-source/website/#specific-sitemap).                                                                                       |
| 7036 | invalid\_chunk\_size                                            | 400         | The chunk size exceeds the embedding model input token limit.                       | Use a smaller [chunk size](https://developers.cloudflare.com/ai-search/configuration/indexing/chunking/) based on the [embedding model limit](https://developers.cloudflare.com/ai-search/configuration/models/supported-models/#embedding).    |
| 7040 | invalid\_custom\_header                                         | 400         | A website data source crawl header is invalid or not allowed.                       | Review [extra headers](https://developers.cloudflare.com/ai-search/configuration/data-source/website/#extra-headers) and remove unsupported headers.                                                                                            |
| 7045 | specific\_sitemaps\_only\_valid\_when\_parse\_type\_is\_sitemap | 400         | Specific sitemaps were provided for an incompatible website data source parse type. | Use [specific sitemaps](https://developers.cloudflare.com/ai-search/configuration/data-source/website/#specific-sitemap) only with sitemap parsing.                                                                                             |
| 7047 | invalid\_url\_location                                          | 400         | A website data source URL location is invalid.                                      | Check the [website data source](https://developers.cloudflare.com/ai-search/configuration/data-source/website/) URL.                                                                                                                            |
| 7050 | fail\_while\_provisioning\_managed\_resources                   | 500         | AI Search could not create managed resources for an instance.                       | Retry the request. Check [Cloudflare Status ↗](https://www.cloudflarestatus.com) and [contact support](https://developers.cloudflare.com/support/contacting-cloudflare-support/) if provisioning continues to fail.                             |
| 7052 | type\_and\_source\_are\_required\_for\_non\_managed\_instances  | 400         | A non-managed instance is missing a type or source.                                 | Provide the required [data source](https://developers.cloudflare.com/ai-search/configuration/data-source/) fields.                                                                                                                              |

## Namespaces

These errors can occur when you create, list, read, update, or delete namespaces, or move instances between namespaces.

| Code | Message                                      | HTTP status | Details                                                                                                 | Recommended action                                                                                                                 |
| ---- | -------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 7022 | ai\_search\_with\_this\_name\_already\_exist | 400         | An instance with this name already exists in the target namespace.                                      | Use a different instance name or [namespace](https://developers.cloudflare.com/ai-search/concepts/namespaces/).                    |
| 7062 | max\_namespaces\_reached                     | 403         | The account reached the limit of 100 namespaces.                                                        | Delete unused namespaces or [request a higher limit](https://developers.cloudflare.com/ai-search/platform/limits-pricing/#limits). |
| 7063 | namespace\_not\_found                        | 404         | The requested namespace does not exist.                                                                 | Check the [namespace](https://developers.cloudflare.com/ai-search/concepts/namespaces/) name.                                      |
| 7064 | namespace\_already\_exists                   | 409         | The namespace already exists.                                                                           | Use a different namespace name or update the existing namespace.                                                                   |
| 7065 | cannot\_modify\_default\_namespace           | 400         | The default namespace is created for every account and cannot be deleted or modified by this operation. | Use a non-default [namespace](https://developers.cloudflare.com/ai-search/concepts/namespaces/) for this operation.                |
| 7066 | namespace\_not\_empty                        | 400         | The namespace still contains instances.                                                                 | Move or delete instances before deleting the [namespace](https://developers.cloudflare.com/ai-search/concepts/namespaces/).        |
| 7067 | namespace\_same\_name                        | 400         | The source and target namespace names are the same.                                                     | Choose a different target [namespace](https://developers.cloudflare.com/ai-search/concepts/namespaces/).                           |

## Tokens

These errors can occur when you create, list, read, update, or delete service API tokens for AI Search.

| Code | Message                              | HTTP status | Details                                    | Recommended action                                                                                                                                               |
| ---- | ------------------------------------ | ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 7012 | ai\_search\_instance\_invalid\_token | 400         | The token is invalid.                      | Create or update the [service API token](https://developers.cloudflare.com/ai-search/configuration/indexing/service-api-token/).                                 |
| 7075 | token\_not\_found                    | 404         | The requested token does not exist.        | Create a new [service API token](https://developers.cloudflare.com/ai-search/configuration/indexing/service-api-token/).                                         |
| 7076 | token\_in\_use\_by\_instances        | 409         | One or more instances still use the token. | Update or delete those instances before deleting the [service API token](https://developers.cloudflare.com/ai-search/configuration/indexing/service-api-token/). |

## Items

These errors can occur when you upload, list, read, download, delete, sync, filter, or inspect indexed items through the Items API or Workers binding.

| Code | Message                                                         | HTTP status | Details                                                                    | Recommended action                                                                                                                                    |
| ---- | --------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| 7032 | ai\_search\_is\_paused                                          | 400         | The instance is paused.                                                    | Resume the instance before uploading items.                                                                                                           |
| 7041 | item\_not\_found                                                | 404         | The requested item does not exist.                                         | Check the item ID.                                                                                                                                    |
| 7042 | item\_key\_already\_exist                                       | 409         | An item with this key already exists.                                      | Use a different filename or manage the existing item with the [Items API](https://developers.cloudflare.com/ai-search/api/items/workers-binding/).    |
| 7044 | unable\_to\_sync\_item                                          | 503         | AI Search could not sync the item.                                         | Retry the operation. Check [indexing error codes](https://developers.cloudflare.com/ai-search/troubleshooting/indexing-error-codes/) for details.     |
| 7053 | this\_operation\_requires\_a\_managed\_instance                 | 400         | The operation only works on managed instances.                             | Use an instance with [built-in storage](https://developers.cloudflare.com/ai-search/configuration/data-source/built-in-storage/).                     |
| 7054 | file\_exceeds\_maximum\_size                                    | 413         | The uploaded file is too large.                                            | Reduce the file size before uploading. Review [file size limits](https://developers.cloudflare.com/ai-search/platform/limits-pricing/#limits).        |
| 7055 | file\_field\_is\_required                                       | 400         | The upload request is missing the file field.                              | Include a file field in the multipart form data.                                                                                                      |
| 7056 | invalid\_metadata\_format                                       | 400         | The upload metadata is not valid.                                          | Send upload metadata as a valid JSON object. See [metadata attributes](https://developers.cloudflare.com/ai-search/configuration/indexing/metadata/). |
| 7058 | invalid\_metadata\_filter                                       | 400         | The metadata filter is not valid.                                          | Check the [filter syntax](https://developers.cloudflare.com/ai-search/configuration/retrieval/filtering/#filter-syntax) and field names.              |
| 7059 | content\_download\_not\_available\_for\_external\_source\_items | 400         | The original content is not available for an item from an external source. | Download the file from the original [data source](https://developers.cloudflare.com/ai-search/configuration/data-source/).                            |
| 7060 | unsupported\_file\_type                                         | 400         | AI Search could not determine a supported content type.                    | Upload a [supported file type](https://developers.cloudflare.com/ai-search/configuration/data-source/#supported-file-types).                          |
| 7072 | filename\_exceeds\_maximum\_length                              | 400         | The filename or item key is longer than 128 characters.                    | Use a filename or item key that is 128 characters or fewer.                                                                                           |

## Jobs

These errors can occur when you create, list, read, cancel, or list logs for sync jobs through the REST API or Workers binding.

| Code | Message                    | HTTP status | Details                                                                           | Recommended action                                         |
| ---- | -------------------------- | ----------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| 7020 | sync\_in\_cooldown         | 429         | A user-triggered sync job was requested within 30 seconds of a previous sync job. | Wait at least 30 seconds before starting another sync job. |
| 7021 | job\_not\_found            | 404         | The requested job does not exist.                                                 | Check the job ID.                                          |
| 7046 | job\_cannot\_be\_cancelled | 400         | The job has already ended and cannot be cancelled.                                | Refresh the job status before cancelling.                  |

## Search and chat

### Search

These errors can occur when you run instance search, cross-instance search, public endpoint search, or `instance.search()` through the REST API, Workers binding, or public endpoints.

| Code | Message                                                   | HTTP status | Details                                                                                                                                    | Recommended action                                                                                                                                                                                                                |
| ---- | --------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 7010 | invalid\_model                                            | 400         | The configured or requested model is invalid.                                                                                              | Use a [supported model](https://developers.cloudflare.com/ai-search/configuration/models/supported-models/).                                                                                                                      |
| 7015 | filter\_or\_operator\_only\_supports\_eq\_filters         | 400         | The or filter contains unsupported operators.                                                                                              | Use supported [filter syntax](https://developers.cloudflare.com/ai-search/configuration/retrieval/filtering/#filter-syntax).                                                                                                      |
| 7016 | filter\_or\_operator\_does\_not\_support\_different\_keys | 400         | The or filter includes multiple metadata keys.                                                                                             | Use the same [metadata attribute](https://developers.cloudflare.com/ai-search/configuration/indexing/metadata/) for every comparison inside the or filter.                                                                        |
| 7039 | missing\_user\_query                                      | 400         | A search request does not include a user query.                                                                                            | Include query or a user message in the [messages format](https://developers.cloudflare.com/ai-search/api/search/rest-api/#search-and-chat).                                                                                       |
| 7057 | invalid\_datetime\_filter\_value                          | 400         | A datetime metadata filter value is invalid.                                                                                               | Use a valid datetime value in your [metadata filter](https://developers.cloudflare.com/ai-search/configuration/retrieval/filtering/).                                                                                             |
| 7058 | invalid\_metadata\_filter                                 | 400         | The metadata filter is not valid.                                                                                                          | Check the [filter syntax](https://developers.cloudflare.com/ai-search/configuration/retrieval/filtering/#filter-syntax) and field names.                                                                                          |
| 7069 | monthly\_query\_quota\_exceeded                           | 429         | The account reached the monthly query quota for its Workers plan.                                                                          | Review [AI Search limits](https://developers.cloudflare.com/ai-search/platform/limits-pricing/#limits), wait for the quota to reset, or upgrade your [Workers plan](https://developers.cloudflare.com/workers/platform/pricing/). |
| 7070 | invalid\_retrieval\_type                                  | 400         | The request set retrieval\_type to a mode the instance's index\_method does not support. Both keyword and hybrid require keyword indexing. | Enable the required [index method](https://developers.cloudflare.com/ai-search/configuration/indexing/hybrid-search/) on the instance, which triggers a reindex. If the override was unintentional, remove retrieval\_type.       |
| 7071 | vectorize\_authentication\_failed                         | 401         | AI Search could not authenticate with Vectorize.                                                                                           | Check the instance configuration and [service API token](https://developers.cloudflare.com/ai-search/configuration/indexing/service-api-token/).                                                                                  |
| 7073 | all\_search\_methods\_failed                              | 500         | All retrieval methods failed.                                                                                                              | Retry the request. Check [indexing error codes](https://developers.cloudflare.com/ai-search/troubleshooting/indexing-error-codes/) and instance configuration.                                                                    |
| 7080 | vectorize\_filter\_not\_serializable                      | 400         | A filter cannot be sent to Vectorize.                                                                                                      | Use JSON-serializable filter values.                                                                                                                                                                                              |
| 7089 | image\_query\_requires\_vector\_index                     | 400         | An image query requires vector indexing.                                                                                                   | Turn on [vector search](https://developers.cloudflare.com/ai-search/configuration/indexing/vector-search/) for the instance and reindex your content, or use an instance that already has vector search enabled.                  |

### Chat

These errors can occur when AI Search retrieves context and generates a response through instance chat completions, cross-instance chat completions, public endpoint chat completions, or `instance.chatCompletions()`.

| Code | Message                               | HTTP status | Details                                                                                                                                    | Recommended action                                                                                                                                                                                                                |
| ---- | ------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 7010 | invalid\_model                        | 400         | The configured or requested model is invalid.                                                                                              | Use a [supported model](https://developers.cloudflare.com/ai-search/configuration/models/supported-models/).                                                                                                                      |
| 7038 | missing\_user\_query                  | 400         | A chat completions request does not include a user query.                                                                                  | Include at least one user message in the [messages format](https://developers.cloudflare.com/ai-search/api/search/rest-api/#search-and-chat).                                                                                     |
| 7069 | monthly\_query\_quota\_exceeded       | 429         | The account reached the monthly query quota for its Workers plan.                                                                          | Review [AI Search limits](https://developers.cloudflare.com/ai-search/platform/limits-pricing/#limits), wait for the quota to reset, or upgrade your [Workers plan](https://developers.cloudflare.com/workers/platform/pricing/). |
| 7070 | invalid\_retrieval\_type              | 400         | The request set retrieval\_type to a mode the instance's index\_method does not support. Both keyword and hybrid require keyword indexing. | Enable the required [index method](https://developers.cloudflare.com/ai-search/configuration/indexing/hybrid-search/) on the instance, which triggers a reindex. If the override was unintentional, remove retrieval\_type.       |
| 7073 | all\_search\_methods\_failed          | 500         | All retrieval methods failed.                                                                                                              | Retry the request. Check [indexing error codes](https://developers.cloudflare.com/ai-search/troubleshooting/indexing-error-codes/) and instance configuration.                                                                    |
| 7089 | image\_query\_requires\_vector\_index | 400         | An image query requires vector indexing.                                                                                                   | Turn on [vector search](https://developers.cloudflare.com/ai-search/configuration/indexing/vector-search/) for the instance and reindex your content, or use an instance that already has vector search enabled.                  |

### Cross-instance search and chat

These errors can occur when you use [cross-instance search or chat](https://developers.cloudflare.com/ai-search/api/search/rest-api/#cross-instance-search-and-chat) to query multiple instances in one request.

| Code | Message                                   | HTTP status | Details                                                             | Recommended action                                                                                                                     |
| ---- | ----------------------------------------- | ----------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 7049 | one\_or\_more\_instance\_searches\_failed | 500         | A cross-instance search failed and return\_on\_failure is disabled. | Retry the request, or allow partial results with return\_on\_failure.                                                                  |
| 7074 | too\_many\_multi\_search\_instances       | 400         | A cross-instance search includes too many instances.                | Reduce instance\_ids to 10 or fewer, the [allowed limit](https://developers.cloudflare.com/ai-search/platform/limits-pricing/#limits). |

When `return_on_failure` is enabled, cross-instance search can return partial results with `errors: [{ instance_id, message: "search_failed" }]`. That response does not use a numeric error code.

### Models and AI Gateway

These errors can occur when a search or chat request calls Workers AI, AI Gateway, or an external model provider.

| Code | Message                                           | HTTP status | Details                                                      | Recommended action                                                                                                                                                                                      |
| ---- | ------------------------------------------------- | ----------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2003 | Rate limited                                      | 429         | AI Gateway rate limited the request.                         | Retry with backoff and review [public endpoint rate limits](https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/#rate-limiting), if applicable.                         |
| 2016 | Prompt blocked due to security configurations     | 424         | AI Gateway Guardrails blocked the prompt.                    | Review [AI Gateway Guardrails](https://developers.cloudflare.com/ai-gateway/features/guardrails/set-up-guardrail/) prompt settings and the prompt content.                                              |
| 2017 | Response blocked due to security configurations   | 424         | AI Gateway Guardrails blocked the response.                  | Review [AI Gateway Guardrails](https://developers.cloudflare.com/ai-gateway/features/guardrails/set-up-guardrail/) response settings and the retrieved content.                                         |
| 7011 | workers\_ai\_fail\_to\_return\_a\_valid\_response | 500         | Workers AI returned an invalid response.                     | Retry the request. Check [Cloudflare Status ↗](https://www.cloudflarestatus.com) and [contact support](https://developers.cloudflare.com/support/contacting-cloudflare-support/) if the error persists. |
| 7019 | workers\_ai\_error                                | 400         | Workers AI returned an error for the request.                | Check the [model](https://developers.cloudflare.com/ai-search/configuration/models/), input, and AI Search options.                                                                                     |
| 7030 | workers\_ai\_timeout                              | 400         | Workers AI timed out.                                        | Retry the request. Check [Cloudflare Status ↗](https://www.cloudflarestatus.com) and [contact support](https://developers.cloudflare.com/support/contacting-cloudflare-support/) if the error persists. |
| 7031 | ai\_gateway\_timeout                              | 400         | AI Gateway timed out.                                        | Retry the request. Check [Cloudflare Status ↗](https://www.cloudflarestatus.com) and [contact support](https://developers.cloudflare.com/support/contacting-cloudflare-support/) if the error persists. |
| 7033 | ai\_gateway\_exception                            | 502         | AI Gateway or the upstream model returned an error.          | Retry the request. Check [AI Gateway](https://developers.cloudflare.com/ai-gateway/) and provider configuration.                                                                                        |
| 7077 | ai\_gateway\_authentication\_error                | 401         | AI Gateway or the upstream provider rejected authentication. | Check provider credentials in [AI Gateway](https://developers.cloudflare.com/ai-gateway/configuration/bring-your-own-keys/).                                                                            |
| 7078 | ai\_gateway\_billing\_error                       | 402         | The upstream provider reported a billing issue.              | Check provider billing status in [AI Gateway](https://developers.cloudflare.com/ai-gateway/configuration/bring-your-own-keys/).                                                                         |
| 7079 | ai\_gateway\_context\_window\_exceeded            | 413         | The request exceeds the model context window.                | Reduce message history, retrieved context, or [result count](https://developers.cloudflare.com/ai-search/configuration/retrieval/result-controls/#maximum-number-of-results).                           |

## Public endpoints

These errors can occur when public search, public chat completions, Model Context Protocol (MCP), snippet analytics, assets, or public endpoint routing fails before the request is proxied to AI Search. Public endpoint `/search` and `/chat/completions` can also return the AI Search API errors listed above.

| Code  | Message                                                        | HTTP status | Details                                                                                             | Recommended action                                                                                                                                                                                                     |
| ----- | -------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 60001 | asset not found                                                | 404         | The requested UI snippet asset path does not exist, such as an incorrect or outdated asset version. | Use the <script> tag from the [UI snippet library](https://developers.cloudflare.com/ai-search/configuration/retrieval/embed-search-snippets/) without changes, and update the asset version if it is outdated.        |
| 60002 | hash not found on url                                          | 404         | The public endpoint hash is missing from the URL.                                                   | Use the [public endpoint URL](https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/#public-url-format) copied from the dashboard.                                                       |
| 60003 | config not found                                               | 404         | The public endpoint configuration was not found.                                                    | Confirm that the [public endpoint](https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/) is enabled.                                                                                   |
| 60004 | ai search not enabled                                          | 404         | The public endpoint is disabled.                                                                    | Enable the [public endpoint](https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/#enabling-and-disabling-public-endpoints) for the instance.                                           |
| 60005 | rate limited                                                   | 429         | The public endpoint rate limit was exceeded.                                                        | Retry after the [rate limit](https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/#rate-limiting) resets.                                                                               |
| 60006 | endpoint not found                                             | 404         | The requested public endpoint route does not exist.                                                 | Use a supported [public endpoint](https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/#available-endpoints).                                                                           |
| 60007 | mcp endpoint disabled                                          | 401         | The MCP endpoint is disabled.                                                                       | Enable MCP for the [public endpoint](https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/).                                                                                            |
| 60008 | search endpoint disabled                                       | 401         | The search endpoint is disabled.                                                                    | Enable the search endpoint in [public endpoint settings](https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/).                                                                        |
| 60009 | chat completions endpoint disabled                             | 401         | The chat completions endpoint is disabled.                                                          | Enable the chat completions endpoint in [public endpoint settings](https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/).                                                              |
| 60010 | method not allowed                                             | 405         | The public endpoint snippet analytics /stats endpoint received an unsupported HTTP method.          | Send snippet analytics requests to /stats with POST.                                                                                                                                                                   |
| 60011 | invalid stats request body                                     | 400         | The public endpoint snippet analytics /stats request body is invalid.                               | Send a valid JSON body with a non-empty events array.                                                                                                                                                                  |
| 60012 | invalid instance\_ids query parameter                          | 400         | A namespace public endpoint received a malformed instance\_ids query parameter.                     | Use a comma-separated instance\_ids value, or omit it to search the configured namespace endpoint instances.                                                                                                           |
| 60013 | instance\_ids contains values outside the configured allowlist | 400         | A namespace public endpoint request includes instance IDs outside its allowlist.                    | Use only instance IDs configured for the namespace public endpoint.                                                                                                                                                    |
| 60014 | path not supported for namespace-kind hash                     | 404         | A namespace public endpoint received an unsupported path.                                           | Use /search, /chat/completions, or /mcp.                                                                                                                                                                               |
| 60015 | request body must be a JSON object                             | 400         | The public endpoint request body is not a JSON object.                                              | Send the request body as a JSON object with Content-Type: application/json, not an array, string, or empty body. See [public endpoint usage](https://developers.cloudflare.com/ai-search/api/search/public-endpoint/). |
| 60016 | method not allowed; this MCP endpoint only accepts POST        | 405         | The MCP endpoint received a non-POST request.                                                       | Send [MCP](https://developers.cloudflare.com/ai-search/api/search/mcp/) requests with POST.                                                                                                                            |
| 60100 | internal error                                                 | 500         | The public endpoint returned an unexpected error.                                                   | Retry the request. Check [Cloudflare Status ↗](https://www.cloudflarestatus.com) and [contact support](https://developers.cloudflare.com/support/contacting-cloudflare-support/) if the error persists.                |

## Troubleshoot API errors

If an API request fails, check the `code` and `message` fields in the error response. For Workers binding calls, check the thrown error `name` and `message`.

For transient service errors, retry with exponential backoff. If an internal or service error persists, [contact Cloudflare support](https://developers.cloudflare.com/support/contacting-cloudflare-support/) with the error code, instance ID, and request timestamp.

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-search/troubleshooting/api-error-codes/#page","headline":"API error codes · Cloudflare AI Search docs","description":"Troubleshoot API and public endpoint errors.","url":"https://developers.cloudflare.com/ai-search/troubleshooting/api-error-codes/","inLanguage":"en","image":"https://developers.cloudflare.com/dev-products-preview.png","dateModified":"2026-07-08","publisher":{"@type":"Organization","name":"Cloudflare","url":"https://www.cloudflare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/ai-search/","name":"AI Search"}},{"@type":"ListItem","position":3,"item":{"@id":"/ai-search/troubleshooting/","name":"Troubleshooting"}},{"@type":"ListItem","position":4,"item":{"@id":"/ai-search/troubleshooting/api-error-codes/","name":"API error codes"}}]}
```