Complete Guide to REST API Error Handling in OutSystems

Before adding handlers, understand which exception types apply: - Communication Exception: triggered when the HTTP request cannot complete — DNS failure, connection refused, TCP timeout. This is the most common error for external API calls. - User Exception: can be raised manually in OnAfterResponse when you detect a bad HTTP status code (4xx, 5xx). - Security Exception: raised when authentication/authorization fails — use this in OnAuthentication callbacks. - AllExceptions: catch-all — use as a fallback after more specific handlers. In OutSystems, unhandled exceptions bubble up to the nearest parent action and eventually to the screen, showing the default error page. Adding explicit handlers breaks this bubble and lets you control the user experience.

Open the Server Action that calls your REST API method. In the action flow, right-click anywhere in the flow canvas → Add Exception Handler → select Communication Exception. This creates a handler branch below the main flow. Inside the handler: 1. Add an Assign node to set meaningful output parameters: IsSuccess = False, ErrorMessage = "Unable to reach the service. Please try again later." 2. Add a LogError node (from System module via Manage Dependencies): Module = your module name, Message = "API call failed: " + CommException.Message, ErrorDetail = CommException.StackTrace 3. Add an End node Action flow with handler: Start → CallExternalAPI (REST method) → Assign (process response) → End [Communication Exception] → Assign (IsSuccess=False, ErrorMessage) → LogError → End

The Communication Exception only fires for network-level failures. HTTP errors (401, 403, 404, 429, 500) from the server are NOT automatically raised as exceptions — OutSystems treats them as successful HTTP responses with an error status code. You must inspect the status code explicitly. To do this: 1. Click your consumed REST API node in Logic tab → Integrations → REST 2. In Properties panel, find On After Response → New OnAfterResponse 3. Open the generated OnAfterResponse action The action receives Response (HTTPResponse) with a StatusCode (Integer) attribute. Build this flow: Start → Switch Case: Response.StatusCode = 401 → Raise Exception (UnauthorizedAccess, Security Exception) Case: Response.StatusCode = 403 → Raise Exception (Forbidden, User Exception) Case: Response.StatusCode = 404 → Raise Exception (ResourceNotFound, User Exception) Case: Response.StatusCode = 429 → Raise Exception (RateLimitExceeded, User Exception) Case: Response.StatusCode >= 500 → Raise Exception (ServerError, Communication Exception) Default → End (2xx responses pass through normally) Create the named User Exceptions first: Logic tab → Exceptions → right-click → Add Exception.

For transient failures (network blips, 503 Service Unavailable, 429 Rate Limited), implement a retry pattern rather than immediately failing. Create a Server Action named CallAPIWithRetry with: - Input: (whatever inputs your API method needs) - Local variables: RetryCount (Integer, default 0), MaxRetries (Integer, default 3), RetryDelayMs (Integer, default 1000), LastError (Text), IsSuccess (Boolean) Action flow: Start → [For Loop: While RetryCount < MaxRetries] → CallExternalAPI → [On Success] Assign (IsSuccess=True) → Exit Loop → [Communication Exception or RateLimitExceeded Exception] → Assign (RetryCount = RetryCount + 1, LastError = exception message) → If (RetryCount >= MaxRetries) → [True] End [False] → Wait (RetryDelayMs milliseconds) → continue loop The Wait action (from System module) pauses the server-side flow. For exponential backoff, set RetryDelayMs = RetryDelayMs * 2 on each iteration.

OutSystems has a built-in logging system accessible in Service Center → Monitoring → Error Log and → Integrations. To write to the Error Log from your exception handlers: 1. In Service Studio, go to Module → Manage Dependencies (Ctrl+Q) 2. Search for (System) module → expand → check LogError and LogWarning actions 3. Click Apply In your exception handlers, add a LogError call: - Module: your module name (Text literal, e.g., "ProductsModule") - Message: descriptive error summary - ErrorDetail: full exception stack trace or response body - StackTrace: exception StackTrace attribute For integration-specific logs, Service Center → Monitoring → Integrations shows every outgoing and incoming REST call with timestamp, URL, HTTP status, request headers, response body, and duration — invaluable for debugging without adding extra logging code.

When exposing REST APIs, return consistent error responses that consumers can parse reliably. Create a Structure under Data tab → Structures → right-click → Add Structure. Name it ErrorResponse with attributes: - Code (Text) — machine-readable error code, e.g., "RESOURCE_NOT_FOUND" - Message (Text) — human-readable description - Details (Text) — optional extended information In your exposed API exception handlers (Logic tab → Exceptions per method): - Catch each typed exception - Assign the ErrorResponse structure - Use SetResponseStatusCode to set the appropriate HTTP status - The ErrorResponse output parameter is automatically serialized to JSON by OutSystems Consumers then always receive: { "Code": "RESOURCE_NOT_FOUND", "Message": "Product with Id 42 was not found.", "Details": "" }