WordPress is_wp_error Example: Handle WordPress Failures Correctly

Last reviewed: May 13, 2026

Many WordPress APIs signal failure by returning a WP_Error object rather than throwing an exception. Code that forgets to check for that ends up treating error objects like arrays, integers, or strings and then fails in confusing downstream places. is_wp_error() is the simple but critical guard that keeps those branches explicit.

This guide shows where to use is_wp_error(), why it should sit close to the API call that may fail, and how to keep error handling readable instead of accidental.

Check the return value immediately after a WordPress call that can fail

<?php
$post_id = wp_insert_post( $payload, true );

if ( is_wp_error( $post_id ) ) {
	error_log( $post_id->get_error_message() );
	return;
}

The closer the check is to the source call, the easier the code is to audit. Delaying the guard makes failures harder to trace and increases the chance of invalid assumptions later in the function.

Do not assume type just because the happy path usually works

The code reference is straightforward: is_wp_error() returns whether the variable is an instance of WP_Error. That matters because many core functions return success values most of the time and only become error objects under edge conditions, failed permissions, or invalid payloads.

Translate the error into a context-appropriate response

Once a WP_Error is detected, the next step depends on context: log it, convert it to an admin notice, transform it into a REST or AJAX response, or stop the current workflow cleanly. The check is only the branch point, not the full error strategy.

Common mistakes

• Checking too late. The error object may already have been misused.
• Assuming an integer, array, or URL was returned because that is the normal case. Edge failures still happen.
• Swallowing the error without context. Operators and logs need a useful signal.
• Treating the check itself as the full recovery plan. The branch still needs a real response strategy.

Production checklist

• Check potential WP_Error returns immediately after the source call.
• Convert the error into a context-appropriate response or log entry.
• Avoid using the value further until the error branch is resolved.
• Review high-risk APIs and form handlers for missing guards.
• Keep failure handling consistent across admin, REST, and AJAX code.

Related reading

Pair this with the wp_send_json_error guide for AJAX failure output and with the rest_ensure_response article to keep successful REST output normalization separate from explicit failure handling.

References and further reading

• WordPress Code Reference: is_wp_error()
• WordPress Code Reference: WP_Error
• WordPress Code Reference: wp_insert_post()