Error handling

The RESTful web services are executed 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 well formed and examine the system log for any errors that may contain additional information.
401	Ensure that the user ID and password 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 may contain additional information.

Error information in payload

When errors occur, a payload that provides an additional 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."/>