min read
July 5, 2024

How to alter the exception message thrown from core REST API

How to alter the exception message thrown from core REST API
Table of contents


Recently, I was working with a REST API where I needed to register a user account. I decided to reuse the core user registration REST API, however, the only problem was that the error messages were not user-friendly.

At that time, I felt the need to alter the exception messages thrown by the core REST API. I got the opportunity to explore the REST API workflow and discovered the 'Event Subscriber' approach that could be used.


Let’s take a very generic scenario: a user tries to create an account with an email ID that already exists. When the REST API endpoint is hit at the backend, a more user-friendly exception message is thrown from the core user registration API using the 'Event Subscriber' approach through customization.

Default core user registers Rest API thrown error message:
    "message": "Unprocessable Entity: validation failed.\nmail: email address is already taken.\n"s

Custom  thrown error message for core user register REST API:   By using event subscriber approach:  see attached screencast for demo:
 "message": "The email address is already taken." 

‍Custom  thrown error message

Steps to alter error messages thrown from core REST API

Steps to alter the error message thrown from core REST API by using the “event subscriber” approach:

1. Create a new service:  “custom_rest_validation.custom_rest_validation_subscriber” in which tags key pass event_subscriber & class key pass name of the class that needs to call when this specified event subscriber calls.

Creation of new service

Note:  Services are defined in a file called 'custom_rest_validation

.services.yml', assuming that your module is named 'custom_rest_validation. This file should be located in the root directory of your module project.

2. Create an event subscriber class that is attached to the newly created service in the above-mentioned step.

Creation of an event subscriber class

Here, getPriority() handles the exceptions we want for JSON calls before core subscribers (with priority -70/-75). Therefore, it is given a higher priority value (-69) than the core subscriber.

getPriority() handleing the exceptions

Here, onException() handles errors for this subscriber and is used to throw custom exception messages. A condition is added so that the custom exception is thrown only for the user registration API and for the email field.

onException() handling errors

Here call the custom parseErrorMsesage($msg) conditionally, which returns a human-readable user-friendly error message “The email address is already taken.” if the user enters an existing email while creating a new user account.

Human-readable user-friendly error message

Note: The event subscriber class CustomExceptionSubscriber.php will be placed in the following folder structure: root_folder_module/src/EventSubscriber/.

We can alter the exception message of the core REST API by extending an "event subscribe" approach.


This approach allows you to utilize the core REST API implementation and integrate desired functionality to provide more human-readable, user-friendly exception messages to end users, thereby enhancing the user experience. The following actions are implemented using the REST API:

  • Get data from the endpoint (GET request)
  • Create data at the endpoint (POST request)
  • Update data at the endpoint (PATCH request)
  • Delete data from the endpoint (DELETE request)

Reference links

For more details about the REST API, you can follow the GitHub demo link. For example, in this demo, I have altered the error message of the core user registration API. If a user enters an existing email ID, a custom exception message will be thrown instead of the default error message from the core REST API for user registration. 

Rest API: documentation

Written by
No art workers.
We'd love to talk about your business objectives