Available Exceptions#

Note: This guide is for Zapier's legacy web builder. For new integrations, use Zapier Visual Builder, which expects standard HTTP errors to be thrown.

In scripting, you have several exception classes at your disposal. Most are used for communicating errors to the user, but a couple do some more interesting bits. See the specifics of each class to find out more.

Heads up: these exceptions are for custom scripting in a Web Builder app. If you're working on a CLI app, check out our CLI error handling docs here.

General Errors#

The most rudimentary exception class is the ErrorException. Use it in situations where the user has something misconfigured with their Zap and will need to take action. Typically, this will be for prettifying 4xx responses and API's that return errors as 200 with a payload that describes the error.

Example: throw new ErrorException('Your error message.');

Note that if a Zap raises too many error messages it will be automatically turned off, so only use these if the scenario is truly an error that needs to be fixed.

Halting Execution#

Any method can be interrupted or "halted" (not success, not error, but stopped for some specific reason) with a HaltedException. You might find yourself using this exception in cases where a required pre-condition is not met. For example, in an action to add notes to a contact where contacts are searched for by email address, you would want to throw a HaltedException if a contact was not found. Unlike the ErrorException, a Zap will never be turned off when this exception is raised (even if it is raised more often than not).

Example: throw new HaltedException('Your reason.');

Any pre_XXX call can be interrupted silently with StopRequestException. This will prevent the request from being made and will never cause a user's Zap to be turned off.

Example: throw new StopRequestException('Your reason.');

Stale Authentication Credentials#

For apps that require manual refresh of authorization on a regular basis, we provide a mechanism to notify users of expired credentials. With the ExpiredAuthException, the current call is interrupted, the zap is turned off (to prevent more calls with expired credentials), and a predefined email is sent out informing the user to refresh the credentials.

Example: throw new ExpiredAuthException('Your message.');

For apps that use OAuth, but do not return a typical 401 when tokens expire, you can use the RefreshTokenException in a post_XXX. This will signal Zapier to attempt to refresh the access token and then repeat the failed call.

Example: throw new RefreshTokenException();

Updating Session Credentials#

For session-based APIs only, stale authorization credentials can be refreshed by throwing the InvalidSessionException. This will tell Zapier to invoke your provided get_session_info() function. Zapier will store these results for you and make them available to every poll and write. We will throw the exception for you if the API responds with a 401 status.

↑ Was this documentation useful? Yes No