Enhance your OutSystems APIs Error Handling

Integration is always a (big) thing. Since I can remember, projects with a high level of integrations, are doomed to take more time than is initially estimated. Nowadays it is not a technology problem (there are several solutions or approaches for the same need), but my experience tells me that everyone has his own interpretation of standards (shouldn't right?!?!), and truly believes that their way is the right way to do it. In this article, I will reflect on my experiences regarding integration with REST services within the OutSystems platform and how I learned to overcome the challenges.


The need to guarantee a high level of integration with the rest of the world (and the world starts in our own house), creates on us architects, the need to define loosely coupled API services for our applications.

Besides the architecture awareness and clearness that creates, OutSystems also agilizes and speeds (a lot) the process of building an API. Having the basic architecture concepts, we are able to easily create an API, following industry patterns, without that much effort. Instead of going for stub-first analysis, to discuss client/consumer best fit, we can start by opening Service Studio, and jointly start building the API. In the end, the automatic generation of the documentation, really helps on sharing and put to use what we have accomplished on a multi-team working meeting. For REST Services, documentation is just a right click of a button.

OutSystems self generated RES API Documentation

To consume the API, we just use the swagger.json to create our connector. Et Voilà!

Taking REST APIs to another (error) level

A proper design of a REST API takes in account that all methods should return proper HTTP status codes. There is a significant list to pick from: success codes such as 200 or 201 or error situations like 400 or 500. However, sometimes this is not enough and more information then a code is needed. For instance, when composing services or business actions and there is the need to understand deeply what is going on, we (might) end up having different error messages with the same HTTP status code.

OutSystems, by default, when we throw out an exception in a REST service, the platform generates automatically a response body with 2 properties: “Errors” and “StatusCode”. “Errors” holds the message that is written in the exception (string), and “StatusCode” is the HTTP status code.

Service Studio with an example of an exception being thrown and the respective response body

The message in the exception can be used to give that extra insight on the error, but is just a string and by promoting masks or “magic” structures inside that string, we would be leveraging a “match on text” approach to figure that out. In my opinion this is not the right way to go!

So why not extended the default error structure with one that can hold all the needed information? This way, we can provide a better insight when an error occurs and allow our consumers a better (programmatically) way to manage the error information on their solutions.

This solution allows us to reuse the current Error Message object that is already in place in our WoW, and with a new API, there is only the need to implement the method “OnResponse” in order to guarantee a correct JSON body after the exception.

Another approach could be making this error structure part of the response and set the right HTTP status code before the end of the transaction. However this solution would be of more effort because we would need to make this structure present in all return objects of all actions for the same endpoint — It’s so SOAP — and also guarantee that all the exceptions would be catched and handled.

For more information about handling REST Errors you should check OutSystems documentation here .

Nice to have

After having all this in place, would be really cool to have a way for the platform to understand the messages and the related HTTP status code, in order to make them visible on the documentation and therefor on the Swagger.

The Swagger 2.0 specification is quite rich and there are several attributes that could be defined on the APIs that we exposed, like x-auth-type or x-throttling-tier. Would be really, really nice to have a way to customize those directly from the Service Studio and make them available on the generated swagger file.

One of the strong factors of OutSystems, is the continuous support for client needs. Maybe we can see some of this ideas in a future version of the platform.


Integration is a never ending story, but software development and applications lifecycles are the same. Features like this ones, promoted by the platform, are really an accelerator on our development process. Move from stub-first analysis into real services ready to use with on-the-fly documentation, besides accelerating development, frees our time to engage other matters.

In the end of the day, if we can continue empowering business, aiming for realistic-fast and time to market solutions with less effort, I am happy!