You can handle and return custom error messages in a Web API by configuring the onError parameter of the a!startProcess() function. This ensures that if the system fails to initiate the process, the requester receives a meaningful JSON response instead of a generic server error.

Node-Level Implementation (Web API Expression)

When defining your Web API, you use a!startProcess() to trigger your business logic. You must configure both outcomes:

1. onSuccess: Returns a success code (typically HTTP 200 or 201) and any relevant process information.
2. onError: Catches failures in process initiation and returns your custom error message using the a!httpResponse() function.

Example Implementation Logic:

Use code with caution.

Handling Failures Inside a Running Process

If the Web API starts successfully but the process fails later (at a specific node like a database write), the Web API has already sent its response and cannot "pull it back". To handle this, use one of these best practices:

1. Synchronous Execution (For Short Processes): Use isSynchronous: true in a!startProcess(). This allows the API to wait for the process to complete (up to 30 seconds) and return a response based on the final status of process variables.
2. Validation Before Starting: Perform data validation within the Web API expression before calling a!startProcess(). If validation fails, return an a!httpResponse with a 400 Bad Request and your custom error details immediately.
3. Callback/Webhook Pattern: If the process is long-running, design the process to call an external API (a "callback") upon failure to notify the original system of the error asynchronously