wp_send_json_error()

💡 云策文档标注

概述

wp_send_json_error() 是一个 WordPress 函数，用于向 Ajax 请求发送 JSON 格式的错误响应。它确保响应中包含 success 键，其值为 false，并可处理 WP_Error 对象以输出详细的错误信息。

关键要点

函数用于发送 Ajax 请求的 JSON 错误响应，自动设置 success 为 false。
参数 $value 可选，若为 WP_Error 对象，则自动处理为包含错误代码和消息的数组；其他类型直接输出。
参数 $status_code 和 $flags 可选，分别用于设置 HTTP 状态码和 json_encode() 选项。
函数内部调用 wp_send_json() 来发送响应，并终止脚本执行。

代码示例

$error = new WP_Error( '001', 'No user information was retrieved.', 'Some information' );
wp_send_json_error( $error );

注意事项

仅调用 wp_send_json_error() 而不带参数可能返回 HTTP 200 状态码，建议设置 $status_code 如 500 以触发错误处理。
函数从 WordPress 3.5.0 版本引入，后续版本增加了参数处理功能。

📄 原文内容

Sends a JSON response back to an Ajax request, indicating failure.

Description

If the $value parameter is a WP_Error object, the errors within the object are processed and output as an array of error codes and corresponding messages. All other types are output without further processing.

Parameters

$valuemixedoptional: Data to encode as JSON, then print and die.

Default:null
$status_codeintoptional: The HTTP status code to output.

Default:null
$flagsintoptional: Options to be passed to json_encode(). Default 0.

More Information

The response object will always have a success key with the value false. If anything is passed to the function in the $data parameter, it will be encoded as the value for a data key.

Source

function wp_send_json_error( $value = null, $status_code = null, $flags = 0 ) {
	$response = array( 'success' => false );

	if ( isset( $value ) ) {
		if ( is_wp_error( $value ) ) {
			$result = array();
			foreach ( $value->errors as $code => $messages ) {
				foreach ( $messages as $message ) {
					$result[] = array(
						'code'    => $code,
						'message' => $message,
					);
				}
			}

			$response['data'] = $result;
		} else {
			$response['data'] = $value;
		}
	}

	wp_send_json( $response, $status_code, $flags );
}

View all references View on Trac View on GitHub

Uses	Description
wp_send_json()`wp-includes/functions.php`	Sends a JSON response back to an Ajax request.
is_wp_error()`wp-includes/load.php`	Checks whether the given variable is a WordPress Error.

Used by	Description
WP_Plugin_Dependencies::check_plugin_dependencies_during_ajax()`wp-includes/class-wp-plugin-dependencies.php`	Checks plugin dependencies after a plugin is installed via AJAX.
wp_ajax_activate_plugin()`wp-admin/includes/ajax-actions.php`	Handles activating a plugin via AJAX.
locate_block_template()`wp-includes/block-template.php`	Finds a block template with equal or higher specificity than a given PHP template file.
wp_ajax_send_password_reset()`wp-admin/includes/ajax-actions.php`	Handles sending a password reset link via AJAX.
wp_ajax_toggle_auto_updates()`wp-admin/includes/ajax-actions.php`	Handles enabling or disable plugin and theme auto-updates via AJAX.
wp_ajax_media_create_image_subsizes()`wp-admin/includes/ajax-actions.php`	Handles creating missing image sub-sizes for just uploaded images via AJAX.
wp_ajax_health_check_get_sizes()`wp-admin/includes/ajax-actions.php`	Handles site health check to get directories and database sizes via AJAX.
wp_ajax_health_check_dotorg_communication()`wp-admin/includes/ajax-actions.php`	Handles site health checks on server communication via AJAX.
wp_ajax_health_check_background_updates()`wp-admin/includes/ajax-actions.php`	Handles site health checks on background updates via AJAX.
wp_ajax_health_check_loopback_requests()`wp-admin/includes/ajax-actions.php`	Handles site health checks on loopback requests via AJAX.
wp_ajax_health_check_site_status_result()`wp-admin/includes/ajax-actions.php`	Handles site health check to update the result status via AJAX.
wp_privacy_process_personal_data_export_page()`wp-admin/includes/privacy-tools.php`	Intercept personal data exporter page Ajax responses in order to assemble the personal data export file.
wp_privacy_generate_personal_data_export_file()`wp-admin/includes/privacy-tools.php`	Generate the personal data export file.
wp_privacy_process_personal_data_erasure_page()`wp-admin/includes/privacy-tools.php`	Mark erasure requests as completed after processing is finished.
wp_ajax_wp_privacy_export_personal_data()`wp-admin/includes/ajax-actions.php`	Handles exporting a user’s personal data via AJAX.
wp_ajax_wp_privacy_erase_personal_data()`wp-admin/includes/ajax-actions.php`	Handles erasing personal data via AJAX.
WP_Customize_Manager::handle_load_themes_request()`wp-includes/class-wp-customize-manager.php`	Loads themes into the theme browsing/installation UI.
WP_Customize_Manager::handle_override_changeset_lock_request()`wp-includes/class-wp-customize-manager.php`	Removes changeset lock when take over request is sent via Ajax.
WP_Customize_Manager::handle_dismiss_autosave_or_lock_request()`wp-includes/class-wp-customize-manager.php`	Deletes a given auto-draft changeset or the autosave revision for a given changeset or delete changeset lock.
WP_Customize_Manager::handle_changeset_trash_request()`wp-includes/class-wp-customize-manager.php`	Handles request to trash a changeset.
wp_ajax_edit_theme_plugin_file()`wp-admin/includes/ajax-actions.php`	Handles editing a theme or plugin file via AJAX.
wp_ajax_get_community_events()`wp-admin/includes/ajax-actions.php`	Handles Ajax requests for community events
WP_Customize_Nav_Menus::ajax_insert_auto_draft_post()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for adding a new auto-draft post.
wp_ajax_search_install_plugins()`wp-admin/includes/ajax-actions.php`	Handles searching plugins to install via AJAX.
wp_ajax_delete_plugin()`wp-admin/includes/ajax-actions.php`	Handles deleting a plugin via AJAX.
wp_ajax_search_plugins()`wp-admin/includes/ajax-actions.php`	Handles searching plugins via AJAX.
wp_ajax_install_theme()`wp-admin/includes/ajax-actions.php`	Handles installing a theme via AJAX.
wp_ajax_update_theme()`wp-admin/includes/ajax-actions.php`	Handles updating a theme via AJAX.
wp_ajax_delete_theme()`wp-admin/includes/ajax-actions.php`	Handles deleting a theme via AJAX.
wp_ajax_install_plugin()`wp-admin/includes/ajax-actions.php`	Handles installing a plugin via AJAX.
WP_Customize_Selective_Refresh::handle_render_partials_request()`wp-includes/customize/class-wp-customize-selective-refresh.php`	Handles the Ajax request to return the rendered partials for the requested placements.
wp_ajax_save_wporg_username()`wp-admin/includes/ajax-actions.php`	Handles saving the user’s WordPress.org username via AJAX.
WP_Customize_Nav_Menus::ajax_load_available_items()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for loading available menu items.
WP_Customize_Nav_Menus::ajax_search_available_items()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for searching available menu items.
wp_ajax_crop_image()`wp-admin/includes/ajax-actions.php`	Handles cropping an image via AJAX.
WP_Customize_Manager::refresh_nonces()`wp-includes/class-wp-customize-manager.php`	Refreshes nonces for the current preview.
wp_ajax_press_this_add_category()`wp-includes/deprecated.php`	Ajax handler for creating new category from Press This.
wp_ajax_update_plugin()`wp-admin/includes/ajax-actions.php`	Handles updating a plugin via AJAX.
wp_ajax_press_this_save_post()`wp-includes/deprecated.php`	Ajax handler for saving a post from Press This.
wp_ajax_destroy_sessions()`wp-admin/includes/ajax-actions.php`	Handles destroying multiple open sessions for a user via AJAX.
Custom_Background::ajax_background_add()`wp-admin/includes/class-custom-background.php`	Handles Ajax request for adding custom background context to an attachment.
wp_ajax_parse_embed()`wp-admin/includes/ajax-actions.php`	Applies Ajax handlers to a string.
wp_ajax_parse_media_shortcode()`wp-admin/includes/ajax-actions.php`
wp_ajax_set_attachment_thumbnail()`wp-admin/includes/ajax-actions.php`	Handles setting the featured image for an attachment via AJAX.
wp_ajax_save_attachment_order()`wp-admin/includes/ajax-actions.php`	Handles saving the attachment order via AJAX.
wp_ajax_send_attachment_to_editor()`wp-admin/includes/ajax-actions.php`	Handles sending an attachment to the editor via AJAX.
wp_ajax_send_link_to_editor()`wp-admin/includes/ajax-actions.php`	Handles sending a link to the editor via AJAX.
wp_ajax_heartbeat()`wp-admin/includes/ajax-actions.php`	Handles the Heartbeat API via AJAX.
wp_ajax_get_revision_diffs()`wp-admin/includes/ajax-actions.php`	Handles getting revision diffs via AJAX.
wp_ajax_save_user_color_scheme()`wp-admin/includes/ajax-actions.php`	Handles auto-saving the selected color scheme for a user’s own profile via AJAX.
wp_ajax_query_themes()`wp-admin/includes/ajax-actions.php`	Handles getting themes from themes_api() via AJAX.
wp_ajax_image_editor()`wp-admin/includes/ajax-actions.php`	Handles image editing via AJAX.
wp_ajax_wp_fullscreen_save_post()`wp-admin/includes/ajax-actions.php`	Handles saving posts from the fullscreen editor via AJAX.
wp_ajax_get_attachment()`wp-admin/includes/ajax-actions.php`	Handles getting an attachment via AJAX.
wp_ajax_query_attachments()`wp-admin/includes/ajax-actions.php`	Handles querying attachments via AJAX.
wp_ajax_save_attachment()`wp-admin/includes/ajax-actions.php`	Handles updating attachment attributes via AJAX.
wp_ajax_save_attachment_compat()`wp-admin/includes/ajax-actions.php`	Handles saving backward compatible attachment attributes via AJAX.
wp_ajax_find_posts()`wp-admin/includes/ajax-actions.php`	Handles querying posts for the Find Posts modal via AJAX.
Custom_Image_Header::ajax_header_crop()`wp-admin/includes/class-custom-image-header.php`	Gets attachment uploaded by Media Manager, crops it, then saves it as a new object. Returns JSON-encoded object details.
Custom_Image_Header::ajax_header_add()`wp-admin/includes/class-custom-image-header.php`	Given an attachment ID for a header image, updates its “last used” timestamp to now.
Custom_Image_Header::ajax_header_remove()`wp-admin/includes/class-custom-image-header.php`	Given an attachment ID for a header image, unsets it as a user-uploaded header image for the active theme.
WP_Customize_Manager::save()`wp-includes/class-wp-customize-manager.php`	Handles customize_save WP Ajax request to save/update a changeset.
WP_Customize_Widgets::wp_ajax_update_widget()`wp-includes/class-wp-customize-widgets.php`	Updates widget settings asynchronously.

Show 58 more Show less

Changelog

Version	Description
5.6.0	The `$flags` parameter was added.
4.7.0	The `$status_code` parameter was added.
4.1.0	The `$value` parameter is now processed if a WP_Error object is passed in.
3.5.0	Introduced.

User Contributed Notes

Skip to note 4 content

milossh

6 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 10You must log in to vote on the helpfulness of this note

Doing just wp_send_json_error(); won’t send error – it will actually return 200 instead. So, if you want to avoid AJAX’ success and trigger error, make sure to add error code, like 500, or whatever you prefer.

Log in to add feedback
Skip to note 5 content

mikelast

8 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note
```
$error = new WP_Error( '001', 'No user information was retrieved.', 'Some information' );

wp_send_json_error( $error );
```
Log in to add feedback

Skip to note 6 content

Codex

10 years ago

-8

Example

jQuery( document ).ready( function() {

	jQuery( '#btn_save' ).on( 'click', function( event ) {
		event.preventDefault();
		jQuery.post( pluginUrl + 'ajax/save_field.php', jQuery( '#my-form' ).serialize(), function( data ) {						
			alert( data.success );
		} );
	} );
} );

save_field.php







Log in to add feedback

云策 WordPress 开发者社区

函数文档

wp_send_json_error()

概述

关键要点

代码示例

注意事项

Description

Parameters

More Information

Source

Changelog

User Contributed Notes

函数文档

概述

关键要点

代码示例

注意事项

Description

Parameters

More Information

Source

Related

Changelog

User Contributed Notes