API error codes

Last updated Oct 1, 2026 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.

How errors are returned

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

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

The 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 and AI Search permissions.
7001 internal_error 500 An internal error occurred. Retry the request. Check Cloudflare Status ↗︎ and contact 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 ↗︎ and contact support if the error persists.
7063 namespace_not_found 404 The requested namespace does not exist. Check the namespace name.
7068 internal_invariant_violated 500 An internal invariant failed. Retry the request. Check Cloudflare Status ↗︎ and contact support if the error persists.
7115 ai_search_models_unavailable 503 AI Search models are temporarily unavailable. Retry the request. Check Cloudflare Status ↗︎ and contact 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 ↗︎ and contact support if the error persists.
7010 invalid_model 400 The configured or requested model is invalid. Use a supported model.
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, or create the gateway in 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 used by the instance.
7013 max_instances_reached 403 The account reached its instance limit. Delete unused instances or request a higher limit.
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.
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.
7024 invalid_domain 400 The website data source domain is invalid. Check the website data source URL.
7028 missing_sitemap 400 AI Search could not find a valid sitemap for the website data source. Add or update the website sitemap.
7029 missing_robots_txt 400 AI Search could not fetch robots.txt for the website data source. Add a valid robots.txt 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 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.
7036 invalid_chunk_size 400 The chunk size exceeds the embedding model input token limit. Use a smaller chunk size based on the embedding model limit.
7040 invalid_custom_header 400 A website data source crawl header is invalid or not allowed. Review authentication 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 only with the sitemap parse type.
7047 invalid_url_location 400 A website data source URL location is invalid. Check the website data source URL.
7050 fail_while_provisioning_managed_resources 500 AI Search could not create managed resources for an instance. Retry the request. Check Cloudflare Status ↗︎ and contact 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 fields.
7101 discover_requires_a_verified_zone_on_this_account 400 A discover crawl requires a verified zone on this account. Use a website in a verified zone on the account, or use the sitemap parse type.
7102 include_external_links_not_allowed 400 Discover crawls cannot follow links outside the verified zone. Turn off include_external_links, or use the sitemap parse type.
7103 sitemap_requires_owned_zone 400 The requested sitemap crawl configuration requires an owned zone. Use a website in a verified zone on the account.
7104 instance_status_modified_concurrently_please_retry 409 Another request changed the instance status concurrently. Retry the request.
7111 source_is_not_a_valid_url_or_existing_r2_bucket 400 AI Search could not infer a source type from the supplied source. Provide an HTTP or HTTPS URL, or the name of an existing R2 bucket on the account.

Custom domains

These errors can occur when you add, change, or remove a custom domain on an instance or namespace public endpoint.

Code Message HTTP status Details Recommended action
7090 custom_domain_not_a_verified_zone_on_this_account 400 The hostname does not belong to an active zone on this account. Add the domain to your Cloudflare account and wait for it to become active.
7091 custom_domain_already_in_use 409 The hostname is already attached to another public endpoint. Remove the custom domain from the other endpoint, or use a different hostname.
7092 custom_domain_provisioning_failed 502 Cloudflare could not provision a certificate for the hostname. Retry the request. Check Cloudflare Status ↗︎ and contact support if the error persists.
7093 custom_domains_require_an_active_public_endpoint 400 The instance or namespace has no active public endpoint. Enable the public endpoint before adding a custom domain.
7096 disabling_the_default_domain_requires_at_least_one_custom_domain 400 default_domain_enabled was set to false without a custom domain. Add a custom domain in the same request, or leave the default hostname enabled.

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.
7062 max_namespaces_reached 403 The account reached the limit of 100 namespaces. Delete unused namespaces or request a higher limit.
7063 namespace_not_found 404 The requested namespace does not exist. Check the namespace 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 for this operation.
7066 namespace_not_empty 400 The namespace still contains instances. Move or delete instances before deleting the namespace.
7067 namespace_same_name 400 The source and target namespace names are the same. Choose a different target namespace.
7097 instances_allowed_contains_unknown_instances 400 An entry in instances_allowed is not an instance in this namespace. Use only instance names that exist in the namespace.
7099 namespace_modified_concurrently_please_retry 409 Another request changed the namespace at the same time. Retry the request.