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