Error handling

The RESTful web services are run in a client/server model. The client application creates and sends an HTTP request to a server, which processes the request and returns an HTTP response to the client application. When the request was successfully processed, the HTTP response contains status information in the HTTP response headers. The response headers contain error information when the request was not successfully processed. In addition to the response headers, error information is provided in the payload of the HTTP response.

The web services are transactional web services unless a particular web service indicates otherwise. For transactional web services, the state of the system is unchanged if an HTTP response indicates an error.

Table 1. Status codes
Status code	Explanation
200	The request was processed successfully.
201	A new entity was created successfully.
304	The HTTP request specified an `ETag` in an `If-None-Match` header. The requested entity was found, but it was unchanged on the server.
400	The request was malformed or an unexpected error occurred during processing. Ensure that the request is correctly formed and examine the system log for any errors that might contain additional information.
401	Ensure that the user ID and password that are provided are correct and the user is in the user repository of the WebSphere® Application Server. If this error occurred during token based authentication, the token might be expired. Retry the failing request and provide a user ID and password instead of the token.
403	The provided user ID does not have the proper permissions to process the request.
404	The requested entity in a read, update, or delete operation was not found.
405	The request does not apply to the specified entity. For example, the entity does not allow update operations, but an HTTP PUT verb was used.
406	The request did not specify media JSON or XML in the HTTP Accept header. Correct the request.
415	The HTTP request did not specify JSON or XML as the content type. Correct the request.
500	An unexpected error occurred during server processing. Examine the system log for any errors that might contain additional information.

Error information in payload

When errors occur, a payload that provides a description is returned in addition to the HTTP status code.

JSON representation

{
  "errorCode": 404,
  "errorDescription": "MessageStandard \"11\" not found."
}

XML representation

<?xml version="1.0" encoding="UTF-8"?>
<error errorCode="404" errorDescription="MessageStandard &quot;11&quot; not found."/>

Overflow errors might cause the wrong value to be displayed in an error message

Invalid message handling of overflow values by a JSON object might cause the wrong value to be displayed in an error message.

If the input value overflows, the message that is returned contains the maximum value for the variable instead of the actual value that was entered. For example, if the long value for ftmTransactionId is 99999999999999999999, the error message that is displayed is:

Invalid value specified for ftmTransactionId: 100,000,000,000,000,000,000

If a validation error other than an overflow occurs, the correct message is displayed.