Error Handling
How WP_Error and is_wp_error() translate to Siren's typed exception system.
WordPress plugin
Last updated: October 26, 2026
WordPress uses a dual-path error model: some functions return WP_Error objects on failure (which you check with is_wp_error()), while others return false or null. This means every call site needs defensive checks, and the type of error you get is inconsistent across the API.
Siren uses PHP exceptions. When something fails, it throws a typed exception. You catch what you need and let the rest propagate.
// WordPress: check for WP_Error after every operation
$result = wp_insert_post($args);
if (is_wp_error($result)) {
echo $result->get_error_message();
return;
}
// Some functions return false instead of WP_Error
$meta = get_post_meta($post_id, '_key', true);
if ($meta === false) {
// Was it an error, or does the meta just not exist?
} // Siren: catch typed exceptions
use PHPNomad\Datastore\Exceptions\RecordNotFoundException;
use PHPNomad\Datastore\Exceptions\DuplicateEntryException;
try {
$program = $this->programs->find($id);
} catch (RecordNotFoundException $e) {
// The program does not exist — handle it
}
try {
$this->collaborators->create($data);
} catch (DuplicateEntryException $e) {
// A collaborator with this email already exists
} Exception reference
Siren and PHPNomad use typed exceptions that tell you exactly what went wrong. Here are the most common ones you will encounter in extension development:
| Exception | When thrown |
|---|---|
RecordNotFoundException | find() with a nonexistent ID, or a query that expects exactly one result finds none |
DuplicateEntryException | Creating a record that violates a uniqueness constraint (e.g., duplicate email) |
RestException | Generic REST error that carries an HTTP status code and message. The status defaults to 400 |
ValidationException | Request validation fails, includes field-level error details |
AuthorizationException | Authenticated but insufficient permissions. Carries 400 unless you pass another status |
AuthenticationException | Not authenticated at all. Carries 400 unless you pass another status |
How does this work in REST controllers?
The REST layer turns a RestException, including its validation, authentication, and authorization subclasses, into an error response with the exception’s status. You don’t need to convert those yourself:
ValidationExceptionreturns a400response with field-level errorsAuthorizationException,AuthenticationException, and every otherRestExceptionreturn the status they carry, which defaults to400- Any other exception thrown from a controller,
RecordNotFoundExceptionandDuplicateEntryExceptionincluded, returns500with “An unexpected error occurred. Sorry, that is all I know.”
So your controller methods can focus on the happy path. Throw a RestException when something goes wrong, and the framework formats the error.
To answer 404 for a missing record, catch RecordNotFoundException and set 404 on the response, or throw a RestException with that status:
use PHPNomad\Datastore\Exceptions\RecordNotFoundException;
use PHPNomad\Rest\Exceptions\RestException;
try {
$program = $this->programs->find($id);
} catch (RecordNotFoundException $e) {
throw new RestException('Program not found.', [], 404);
}
An exception thrown from a controller comes back in Siren’s {"error": {"message", "context"}} shape with its status, 401 and 403 included. On WordPress, only a 401 or 403 thrown by middleware becomes WordPress’s {code, message, data} error, with rest_not_logged_in or rest_forbidden. To refuse in WordPress’s shape, write a middleware that throws with the status, the way Siren’s event ingestion middleware does:
namespace MyPlugin\Middleware;
use PHPNomad\Auth\Enums\ActionTypes;
use PHPNomad\Auth\Models\Action;
use PHPNomad\Http\Interfaces\Request;
use PHPNomad\Rest\Exceptions\AuthenticationException;
use PHPNomad\Rest\Exceptions\AuthorizationException;
use PHPNomad\Rest\Interfaces\Middleware;
use Siren\Programs\Core\Models\Program;
class RequireProgramEditor implements Middleware
{
public function process(Request $request): void
{
$user = $request->getUser();
if (!$user) {
throw new AuthenticationException('Sign in to use this route.', [], 401);
}
if (!$user->canDoAction(new Action(ActionTypes::Update, Program::class))) {
throw new AuthorizationException("You don't have permission to do that.", [], 403);
}
}
}
Return an instance from your controller’s getMiddleware() in place of, or before, createAuthMiddlewareFromCurrentContext().
What should I catch in extension code?
In extension code (listeners, transformers, services), catch the exceptions you can meaningfully handle and let the rest propagate. Common patterns:
// In a transformer: catch RecordNotFoundException when looking up mappings
try {
$transaction = $this->transactions->find($mappedId);
} catch (RecordNotFoundException $e) {
// No Siren transaction for this order — return null to skip
return null;
}
// In a listener: catch and log, but don't crash the event pipeline
try {
$this->externalService->sync($data);
} catch (\Exception $e) {
$this->logger->logException($e);
// The sync failed, but the rest of the pipeline should continue
}
The transformer pattern is especially important. Transformers return null to skip events, so catching “record not found” and returning null is the standard way to handle cases where the data does not exist.
If you do not catch an exception in a listener, it will propagate up and may prevent subsequent listeners for the same event from executing. When in doubt, catch broadly in listeners and log the exception so you can diagnose issues without breaking the event pipeline.
Where to go next
For controllers and middleware in general, see REST API Patterns. For the full REST error response format (including validation error details), see the Resource Reference Introduction.
For the full PHPNomad framework documentation, see PHPNomad.