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.

Built-in Error Handling

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:

  1. Sets the HTTP status code of the response according to the type of the issue.
  2. For each issue detected in the validation step, it adds an error message to the list of errors in the response body;
  3. Adds the HTTP status code to the response body;
  4. Sends the response immediately to the caller, without processing the action flow defined for that request.

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:

  1. Rolls back any modification made to the database;
  2. Sets the HTTP status code of the response to 500 - Internal Server Error;
  3. Adds the error message of the raised exception to the response body;
  4. Adds the HTTP status code 500 to the response body;
  5. Sends the response to the caller.

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.

Add a Custom Error Message

If you want to add a custom error that appears in the response body, the steps you take are the following:

  1. Create a new User Exception;
  2. Raise the user exception in the REST API method;
  3. Test the method.


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:

1. Create a User Exception

Create a new User Exception called 'DeletionNotAllowed'. Learn how to create User Exceptions.

2. Raise the User Exception

To raise your user exception, proceed as follows:

  1. Add a Raise Error element to the action flow of the REST API method;
  2. Set it to raise the 'DeletionNotAllowed' user exception;
  3. Set the Error Message property to "Record is protected against deletion".

3. Test the Method

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.

See Also

User Exceptions | Built-in HTTP Status Codes