Skip to main content




Service Studio version:

Customize REST API Responses

  • Edit
    Collaborate with us
    Edit this page on GitHub
  • We've been working on this article. Please let us know how useful this new version is by voting.

    OutSystems allows you to customize the information sent in responses when exposing a REST API.

    For that, do the following:

    1. In the Logic tab, open the Integrations folder.

    2. In the exposed REST API, set the property On Response to New OnResponse.

      REST API in Service Studio

    3. Open the OnResponse callback action that's now available under the REST API.

    4. Design the logic to customize the information of the response.

      Input and output parameters of OnResponse callback

      You can get the text of the response by accessing the "ResponseText" attribute of the "Response" input parameter or its binary contents by accessing the "ResponseBinary" attribute.

      Make sure to set the "CustomizedResponse" output to the request after your preprocessing.

      The "ResponseText" and "ResponseBinary" attributes of the "Response" input parameter contain only the response body in serialized JSON format and in binary format, respectively. They don't include the headers that are part of the response.

      If you fill in the "ResponseText" attribute of the "CustomizedResponse" output parameter with some value, this is the response that's sent to the API client, even if you also set the "ResponseBinary" attribute.

    Once defined and configured in the REST API, OutSystems executes the OnResponse callback for all methods exposed by the REST API.

    Example use case

    You can use the OnResponse callback to customize the response when an exception occurs. You may want to improve the default response, similar to the following:

        "Errors": [
            "The 'Id' URL parameter is missing in the request.",
            "The request body is missing."
        "StatusCode": 400

    You can provide a response with more detail, like in the following example:

        "HTTPStatus": {
            "HTTPCode": 404,
            "developerMessage": "Not Found",
            "userMessage": "The server can not find the requested resource. In an API, this can mean that the endpoint is valid but the resource itself does not exist.",
            "errorCode": "404",
            "moreInfo": "For more information please visit"

    Check the blog post How to Implement HTTP Status Codes When Exposing a REST API in OutSystems and the application REST HTTP Codes in the OutSystems Forge for more information on implementing this example use case.

    • Was this article helpful?