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:

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

Example Implementation Logic:

a!startProcess(

processModel: cons!AV_PROCESS_MODEL,

processParameters: { data: http!request.body },

onSuccess: a!httpResponse(

statusCode: 200,

body: a!toJson({ status: "SUCCESS", message: "Process started" })

),

onError: a!httpResponse(

statusCode: 500,

headers: { a!httpHeader(name: "Content-Type", value: "application/json") },

body: a!toJson({

status: "ERROR",

errorCode: "PROC-001",

customMessage: "The process could not be initiated. Please check the input payload."

})

)

)

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:

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.
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.
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