API error codes·续1

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.
7075 token_not_found 404 The requested token does not exist. Create a new 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.

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.
7044 unable_to_sync_item 503 AI Search could not sync the item. Retry the operation. Check 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.
7054 file_exceeds_maximum_size 413 The uploaded file is too large. Reduce the file size before uploading. Review file size 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.
7058 invalid_metadata_filter 400 The metadata filter is not valid. Check the 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.
7060 unsupported_file_type 400 AI Search could not determine a supported content type. Upload a supported file type.
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.
7095 item_write_rate_limited 429 The item could not be written because storage temporarily rate limited the request. Retry with backoff.
7100 full_page_content_unavailable 403 Full page downloads are unavailable for discover-crawled content. Use search results or item chunks to retrieve cited excerpts.
7113 client_disconnected_during_upload 499 The client disconnected before the upload completed. Reconnect and upload the file again.
7114 ai_search_instance_overloaded 429 The instance is temporarily overloaded. Retry after the Retry-After delay.

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

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.
7015 filter_or_operator_only_supports_eq_filters 400 The or filter contains unsupported operators. Use supported filter syntax.
7016 filter_or_operator_does_not_support_different_keys 400 The or filter includes multiple metadata keys. Use the same metadata attribute 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.
7057 invalid_datetime_filter_value 400 A datetime metadata filter value is invalid. Use a valid datetime value in your metadata filter.
7058 invalid_metadata_filter 400 The metadata filter is not valid. Check the 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, wait for the quota to reset, or upgrade your Workers plan.
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 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.
7073 all_search_methods_failed 500 All retrieval methods failed. Retry the request. Check 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 for the instance and reindex your content, or use an instance that already has vector search enabled.
7105 metadata_filter_unknown_field 400 The metadata filter references a field that is not indexed. Use a system metadata field or a configured custom metadata field.

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.
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.
7069 monthly_query_quota_exceeded 429 The account reached the monthly query quota for its Workers plan. Review AI Search limits, wait for the quota to reset, or upgrade your Workers plan.
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 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 and instance configuration.
7089 image_query_requires_vector_index 400 An image query requires vector indexing. Turn on 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 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.

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, if applicable.
2016 Prompt blocked due to security configurations 424 AI Gateway Guardrails blocked the prompt. Review AI Gateway Guardrails prompt settings and the prompt content.
2017 Response blocked due to security configurations 424 AI Gateway Guardrails blocked the response. Review AI Gateway Guardrails 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 ↗︎ and contact support if the error persists.
7019 workers_ai_error 400 Workers AI returned an error for the request. Check the model, input, and AI Search options.
7094 workers_ai_free_allocation_exceeded 402 The managed Workers AI allocation for AI Search was exceeded. Retry later. If the error persists, contact support.
7030 workers_ai_timeout 400 Workers AI timed out. Retry the request. Check Cloudflare Status ↗︎ and contact support if the error persists.
7031 ai_gateway_timeout 400 AI Gateway timed out. Retry the request. Check Cloudflare Status ↗︎ and contact 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 and provider configuration.
7077 ai_gateway_authentication_error 401 AI Gateway or the upstream provider rejected authentication. Check provider credentials in AI Gateway.
7078 ai_gateway_billing_error 402 The upstream provider reported a billing issue. Check provider billing status in AI Gateway.
7079 ai_gateway_context_window_exceeded 413 The request exceeds the model context window. Reduce message history, retrieved context, or result count.
7117 ai_gateway_credential_not_found 400 No stored credential was found for the upstream provider. Add the provider key in AI Gateway.