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.

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:

These errors can occur across most AI Search API paths.

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

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

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

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

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

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.

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().

These errors can occur when you use cross-instance search or chat to query multiple instances in one request.

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.

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

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.

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 with the error code, instance ID, and request timestamp.