wp_send_json_error()WP 3.5.0

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

Used to return errors in AJAX requests. The response will always contain success=false element. Terminates the php script (die).

The function also sets the header:

@header( 'Content-Type: application/json; charset=' . get_option( 'blog_charset' ) );

and die the PHP script via die().

Just calling wp_send_json_error() will not set the error response - it will return 200 instead. Therefore, if you want to indicate that AJAX request failed, be sure to specify error code, for example 500, in $status_code parameter.

Since version 4.1. If you pass WP_Error object into the $data parameter, it will be processed and the function will return an array with an error message. That is, the function understands the passed WP_Error object.

wp_send_json_success() — the opposite of this function. Returns a successful answer.

No Hooks.

Return

null. Displays the data on the screen and terminates php.

The type of data returned, before encoding to JSON:

array( 'success' => false );

If $data parameter is specified:

array( 'success' => false, 'data' => $data );

Usage

wp_send_json_error( $data, $status_code, $options );
$data(mixed)
Data to encode as JSON, then print and die.
Default: null
$status_code(int)
The HTTP status code to output. What are the status codes, see here.
Default: null
$options(int)

Options to be passed to json_encode(). A bitmask made up of values:

JSON_FORCE_OBJECT
JSON_HEX_QUOT
JSON_HEX_TAG
JSON_HEX_AMP
JSON_HEX_APOS
JSON_INVALID_UTF8_IGNORE
JSON_INVALID_UTF8_SUBSTITUTE
JSON_NUMERIC_CHECK
JSON_PARTIAL_OUTPUT_ON_ERROR
JSON_PRESERVE_ZERO_FRACTION
JSON_PRETTY_PRINT
JSON_UNESCAPED_LINE_TERMINATORS
JSON_UNESCAPED_SLASHES
JSON_UNESCAPED_UNICODE
JSON_THROW_ON_ERROR

The meaning of these constants is explained on the JSON constants page.

Examples

1

#1 Passing WP_Error to $data

You can pass a WP_Error object to the $data parameter:

$error = new WP_Error( 'error_code', 'ERROR: Wrong credentials.' );

wp_send_json_error( $error );

Now when receiving data in JS the response will contain an array of all errors in such form (usually there is only one element):

{
	success: false,
	data: [
		0: { code: 'error_code', message: 'ERROR: Wrong credentials.' }
	]
}

I.e. you can get an error message like this:

response.data[0].message
0

#2 Return an error in JSON format on AJAX response

This jQuery code sends an AJAX request to the plugin page ajax/save_field.php:

fetch( `${ pluginUrl }/ajax/save_field.php` )
	.then( resp => resp.json() )
	.then( res => {
		if( res.success ){
			alert( res.data )
		}
		// error
		else {
			alert( res.data )
		}
	} )

This is the code of the file /ajax/save_field.php that handles the passed request. It shows how to return errors:

<?php

$nonce = $_POST['_wpnonce_name'];

// print json given success=false
if ( empty( $_POST ) || ! wp_verify_nonce( $nonce, 'my-nonce' ) ) {
	wp_send_json_error( 'Error messege' ); 
}

// it is not necessary to use die here

wp_send_json_success( 'OK message' ); 

Changelog

Since 3.5.0 Introduced.
Since 4.1.0 The $data parameter is now processed if a WP_Error object is passed in.
Since 4.7.0 The $status_code parameter was added.
Since 5.6.0 The $options parameter was added.

wp_send_json_error() code WP 6.4.3

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

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

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

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