Exception handling

There are multiple reasons that exceptions occur in REST API operations. For example, the exception can be one of the following:
  • Exception due to problems with the input sent by the client.
  • Exception due to implementation bugs.
  • Exception due to other runtime failures specific to the server environment. For example, the API could not access the database, or, another user changed the data concurrently with the API request.

Status codes

PolicyCenter exception handling classes return standard HTTP status codes:
  • The REST API framework roughly maps successful operations to the 2xx class of HTTP response codes.
  • The REST API framework roughly translates client input errors to the 4xx class of HTTP response codes.
  • The REST API framework roughly maps implementation bugs or other runtime problems to the 5xx class of HTTP response codes.

The REST API framework manages many of the types of potential errors automatically. For example, if the request does not validate against the declared parameters or the JSON schema for the request body, the framework returns a 400 response with the details of the issue. The framework does the same with authentication or authorization issues, bad content types, and other similar types of issues.

Standard error format

The standard format for error messages contains the following JSON elements.
Element Description
status HTTP status code on the response, included on the payload. For errors, the HTTP status code indicates the broad category of failure
errorCode Specific code for the error, to provide more information than that provided by the status code. Typically, the error class sets this value to the name of the exception class, unless a custom exception subclass sets it explicitly to some other value.
userMessage, developerMessage Error messages that describe the problem or issue in more detail. If the error message specifies both a userMessage and a developerMessage, Guidewire recommends the following:
  • Phrase userMessage in such a way as to make it possible to surface the error message directly to the PolicyCenter user.
  • Phrase developerMessage so as to be useful to the developer creating the client that calls the REST API.
details Error message can also contain an array of additional details that describe the problem. The exact properties on the details object can vary depending on the exception type
The following example illustrates an error message for a request that failed. In this case, the request payload was missing the 'subject' property on the root JSON object, which the JSON specification specifically requires.
{
  "status": 400,
  "errorCode": "gw.api.rest.exceptions.BadInputException",
  "userMessage": "The request parameters or body had issues",
  "developerMessage": "The request parameters or body had issues. See the details elements for exact details of the problems.",
  "details": [
    {
      "message": "The 'subject' property is required",
      "properties": {
        "parameterName": "body",
        "parameterLocation": "body",
        "lineNumber": 1
      }
    }
  ]
}