Wordpress - How to catch/what to do with a WP Error Object

1. Assign return of the function to the variable.

2. Check the variable with is_wp_error().

3. If true handle accordingly, for example trigger_error() with message from WP_Error->get_error_message() method.

4. If false - proceed as usual.

Usage:

function create_custom_post() {
  $postarr = array();
  $post = wp_insert_post($postarr);
  return $post;
}

$result = create_custom_post();

if ( is_wp_error($result) ){
   echo $result->get_error_message();
}

Hei,

first, you check weather your result is a WP_Error object or not:

$id = wp_insert_post(...);
if (is_wp_error($id)) {
    $errors = $id->get_error_messages();
    foreach ($errors as $error) {
        echo $error; //this is just an example and generally not a good idea, you should implement means of processing the errors further down the track and using WP's error/message hooks to display them
    }
}

This is the usual way.

But the WP_Error object can be instanciated without any error occuring, just to act as a general error store just in case. If you want to do so, you can check if there are any errors by using get_error_code():

function my_func() {
    $errors = new WP_Error();
    ... //we do some stuff
    if (....) $errors->add('1', 'My custom error'); //under some condition we store an error
    .... //we do some more stuff
    if (...) $errors->add('5', 'My other custom error'); //under some condition we store another error
    .... //and we do more stuff
    if ($errors->get_error_code()) return $errors; //the following code is vital, so before continuing we need to check if there's been errors...if so, return the error object
    .... // do vital stuff
    return $my_func_result; // return the real result
}

If you do that, you can then check for an process the returned error just as in the wp_insert_post() example above.

The Class is documented on the Codex.
And there's also a little article here.