WordPress wp_send_json_error Example: Return AJAX Failures Cleanly

Last reviewed: May 8, 2026

Many WordPress AJAX handlers fail messily. Some echo raw strings, some return a 200 response for every failure, and some mix browser-oriented HTML errors into code paths that should be machine-readable. wp_send_json_error() gives AJAX handlers a clear failure response shape and keeps the contract closer to what front-end code expects.

This guide shows how to return structured WordPress AJAX failures cleanly and why the HTTP status code still matters.

Return a structured error response instead of ad hoc output

<?php
if ( ! current_user_can( 'edit_posts' ) ) {
	wp_send_json_error(
		array( 'message' => 'You are not allowed to update this note.' ),
		403
	);
}

if ( empty( $_POST['note'] ) ) {
	wp_send_json_error(
		array( 'message' => 'The note field is required.' ),
		422
	);
}

The function always sends a JSON object whose success key is false. That predictable shape makes client-side handling cleaner than mixing raw strings and unstructured output.

Set an HTTP status code deliberately

The code reference notes an important detail: calling wp_send_json_error() without a status code does not automatically make the response an HTTP error. If the client should treat the request as forbidden, invalid, or failed, send the appropriate status explicitly.

Use WP_Error when the failure already exists in that form

If upstream validation or business logic already returns a WP_Error object, the helper can serialize those errors into structured output. That can reduce glue code when a handler already uses WordPress-style error objects internally.

Common mistakes

• Returning plain strings from an AJAX endpoint. This creates messy client contracts.
• Skipping the status code. The JSON body may say error while the HTTP layer still says success.
• Using it before permission checks are complete. The handler still needs correct authorization logic.
• Leaking internal diagnostics to the browser. Error payloads should stay useful but controlled.

Production checklist

• Use wp_send_json_error() for machine-readable AJAX failure output.
• Set a meaningful HTTP status code for forbidden, invalid, or failed requests.
• Keep permission checks separate from response formatting.
• Return stable payload keys the front end can handle consistently.
• Review error messages for unnecessary internal detail.

Related reading

Pair this with the check_ajax_referer guide for request verification and with the admin AJAX article for the broader logged-in handler pattern.

References and further reading

• WordPress Code Reference: wp_send_json_error()
• WordPress Code Reference: WP_Error
• WordPress Code Reference: wp_send_json()