Exception handling classes

Whether any exception thrown from within the handler method itself translate to HTTP response codes depends on whether the exception class implements the HasErrorInfo interface:

  • If a thrown exception implements the HasErrorInfo interface, the framework constructs the response based on the status code and error details on the exception.
  • If a thrown exception does not implement the HasErrorInfo interface, the framework translate the exception into a generic 500 "internal server error" HTTP response.
A handler method can use any exception that implements the gw.api.exception.HasErrorInfo interface, including custom exception subtypes. However, in general, the exception classes defined in the gw.api.rest.exceptions package are suitable for mapping to common error cases. For example:
NotFoundException A method can throw a NotFoundException exception if the REST framework cannot find an entity ID referenced from a path parameter in the database.
BadInputException A method can throw a BadInputException exception if the input fails some additional validation performed by the method handler. In this way, it is possible to add additional validations in the method that you cannot declare in the schema. For example, you can throw a BadInputException exception that translates to a 400 error.

Exception handler classes

Any exception class that you create must do one of the following:
  • Extend the RestExceptionWithErrorInfo class
  • Implement the HasErrorInfo interface

Any API handler class that you create must check for error cases that the REST framework does not handle automatically. The handler class must specifically throw the appropriate exceptions in cases in which the error is caused by the input on the client side.

Stack traces

The API client response returns a stack trace for internal server errors, if the server is not in production mode. Custom exception classes can trigger the inclusion of stack traces by extending the RestExceptionWithErrorInfo class and calling the parent (super) constructor with the Boolean includeCause argument set to true:
  • super(statusCode, userMessage, developerMessage, details, includeCause)
For example:
  • super(500, userMessage, developerMessage, details, true)
In the base configuration, only the InternalServerErrorException class passes true for this argument.

Rewriting error messages

It is possible to rewrite error information using the rewriteErrorInfo method on the IRestDispatchPlugin implementation class.

Handler classes that return a Response object

It is possible for an API handler class to return a Response object that explicitly sets the status code to a 4xx or 5xx status code. While this is legal to do, using a Response object to set the error code also makes it harder to ensure that the error format is consistent across different classes of errors.

In such cases, the framework considers the request to be successful as no exceptions were thrown and the handler class completed successful. This causes the handler class to invoke the rewriteResponse method on the IRestDispatchPlugin class instead of the rewriteErrorInfo method. In general, Guidewire recommends that you use a custom exception class that implements the HasErrorInfo interface and then throw an exception, rather than returning an explicit Response object with a 4xx or 5xx status code.