API 错误代码

当对 AI Search API 或公共端点的请求失败时，会返回本页记录的错误之一。

条目在索引过程中发生的错误另行处理。请参阅 索引错误代码。

REST API 与公共端点以 JSON 封装返回错误：

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

Workers 绑定（binding） 会抛出异常。异常的 message 包含 AI Search 错误消息，例如 ai_search_not_found。

对于 Workers 绑定调用，抛出的错误类取决于上游 HTTP 状态：

这些错误可能出现在大多数 AI Search API 路径上。

这些错误可能在通过 REST API 或 Workers 绑定创建、读取、更新、删除 AI Search 实例或获取统计信息时发生。

这些错误可能在创建、列出、读取、更新或删除命名空间，或在命名空间之间移动实例时发生。

这些错误可能在创建、列出、读取、更新或删除 AI Search 的服务 API 令牌时发生。

这些错误可能在通过 Items API 或 Workers 绑定上传、列出、读取、下载、删除、同步、过滤或检查已索引条目时发生。

这些错误可能在通过 REST API 或 Workers 绑定创建、列出、读取、取消同步作业或列出其日志时发生。

这些错误可能在通过 REST API、Workers 绑定或公共端点运行实例搜索、跨实例搜索、公共端点搜索或 instance.search() 时发生。

这些错误可能在 AI Search 通过实例聊天补全、跨实例聊天补全、公共端点聊天补全或 instance.chatCompletions() 检索上下文并生成响应时发生。

这些错误可能在使用 跨实例搜索或聊天 在一次请求中查询多个实例时发生。

当启用 return_on_failure 时，跨实例搜索可以返回带有 errors: [{ instance_id, message: "search_failed" }] 的部分结果。该响应不使用数字错误代码。

这些错误可能在搜索或聊天请求调用 Workers AI、AI Gateway 或外部模型提供商时发生。

这些错误可能在公共搜索、公共聊天补全、Model Context Protocol (MCP)、代码片段分析、资源或公共端点路由在请求被代理到 AI Search 之前失败时发生。公共端点 /search 与 /chat/completions 也可能返回上文列出的 AI Search API 错误。

如果 API 请求失败，请检查错误响应中的 code 与 message 字段。对于 Workers 绑定调用，请检查抛出错误的 name 与 message。

对于瞬时服务错误，请使用指数退避重试。如果内部或服务错误持续，请向 Cloudflare 支持 提供错误代码、实例 ID 与请求时间戳。