Introducing Throw Statements in Deluge

Introducing Throw Statements in Deluge

Hello everyone,

We're introducing a powerful addition to Deluge that gives you more precise control over error handling in your scripts.
Whether you're calling an external API, validating user input, or enforcing a business rule, there are moments when a script needs to stop and flag that something went wrong. Take API calls as an example: a script using invokeUrl gets marked as successful the moment the call is made, not when it actually succeeds. That means an API returning a 400, a rejected payload, or a silently failed transaction can all leave the script looking green while the business process behind it breaks.

Handling this today involves a lot of workarounds. It works, but it's tedious. That's why we're introducing the throw statement in Deluge.

What throw does

throw lets you explicitly raise a custom exception the moment something goes wrong, whether it's an API returning an error, a business rule being violated, or a validation check failing. The script stops right there and passes control to the nearest matching catch block.

throw and catch, working together
throw is designed to work hand-in-hand with catch. Think of it as a two-part flow:
  1. throw raises the exception with the details you define.
  2. catch picks up the exception and decides what to do with it, whether retrying, notifying someone, or handling it gracefully.

If no catch block is available to handle a thrown exception, the script terminates with the exception details, so a failure never gets silently swallowed. 

A quick example

Here's a simple use of throw. If the order quantity is zero or negative, the script raises an exception and the catch block handles it:
Quote
try
{
   if(orderQuantity <= 0)
   {
       throw "Invalid order quantity";
   }
   info "Order accepted.";
}
catch(e)
{
   info "Order failed: " + e;
   info "Line number: " + e.lineNo;
}

Now, let's consider a business scenario. Say you have a Deluge function that pushes a new invoice to an external accounting service:

Quote
invoicePayload = Map();
invoicePayload.put("invoice_id", "INV-1042");
invoicePayload.put("amount", 2500);
invoicePayload.put("currency", "USD");

try
{
   response = invokeUrl
   [
       url : "https://api.example.com/invoices"
       type : POST
       parameters : invoicePayload
   ];
   if(response.get("status") != "success")
   {
       throw {
           "message" : "Invoice sync failed",
           "data" : response
       };
   }
   info "Invoice synced successfully.";
}
catch(e)
{
   info "Sync failed: " + e.message;
   info "API response: " + e.data;
   info "Line number: " + e.lineNo;
}
Here, we've explicitly told throw to attach the API response as part of the exception. When the accounting service rejects the invoice, the script stops, and the calling catch block receives the full response for inspection (exactly the context needed to log, retry, or alert).

What else throw unlocks

A few things worth knowing once you start using throw:
Rich exception details
Along with a message, you can attach data of any Deluge type. This is what makes exceptions useful downstream. Some examples of what to pass:
  1. The API response, for API-related failures
  2. The record ID and current field values, for validation errors
  3. The user input that triggered the issue, for form-level checks
  4. Any custom object that helps the catch block understand what went wrong

Re-throwing exceptions
Sometimes one catch block isn't enough. Re-throwing lets you handle an exception at more than one level. You can nest try-catch blocks inside each other. An inner catch can do its own work with the exception, then pass the same exception up to an outer catch by throwing it again.
Sample code:

Quote
try
{
   try
   {
       // sync logic here
   }
   catch(e)
   {
       info "Sync failed: " + e.message;   // local logging
       throw e;                                    // re-throw to outer catch
   }
}
catch(e)
{
   // outer handler: notify the user, roll back, alert admin, etc.
}
The inner catch records the failure, and the outer catch handles the response like notifying or rolling back, without either duplicating the other's logic.

Exception propagation
If a function raises an exception without handling it, Deluge moves the exception up to the script that called the function, giving that script the chance to catch it. This is what makes reusable validation functions possible: you can write validation logic once, throw inside it freely, and let the calling script decide how to respond. 

Documentation

For detailed information, refer to the throw statement help page.

We believe the throw statement will be a great value addition to your Deluge scripts. Give it a try and let us know what you think.

If you have any questions or need assistance, feel free to reach out; we're always happy to help.

Regards,
The Zoho Creator Team