When a REST API method runs into an error, it's useful to send a meaningful error message to the client about what happened. Some of the problems are automatically handled for you, but you have the possibility to add custom error handling to your logic.
When OutSystems Platform receives a REST API request, it first checks if it's valid. See the detected problems in the Built-in HTTP Status Codes article.
If it detects any issue, it does the followings:
Example response body with errors:
If the Platform doesn't detect any issue with the request, it starts executing the action flow of the REST API method. If there is any unhandled exception during the execution, the built-in error handler catches it, and does the followings:
Example response body in this case:
The above errors are also logged by the OutSystems Platform, you can view the logs in the environment management console, under Monitoring, in the Integrations tab.
If you want to add a custom error that appears in the response body, the steps you take are the following:
We have an application to manage contacts. Some contact records are protected against deletion. We want to extend the existing DeleteContact method with a detailed error message when the contact is protected.
To implement this, follow these steps:
Create a new User Exception called 'DeletionNotAllowed'. Learn how to create User Exceptions.
To raise your user exception, proceed as follows:
We've deployed the application to our environment in the public cloud. To test the method with curl, we use the following command:
curl -X DELETE https://osacademy.outsystemscloud.com/ContactsAPI/rest/Contacts/DeleteContact?ContactId=186
The result is:
The status code of the response is 500, as this is the status code that OutSystems uses for application errors.
User Exceptions | Built-in HTTP Status Codes