Error Handling, Logging and Messaging
To aid in the testing, certification and sharing of click-to-install apps, developers are requested to provide graceful error handling for any OCLC Web services with which the app interacts. When an error occurs, a human-readable and understandable error message should be displayed to the user consuming the application.
Some typical user error messages might include:
- Authentication failed
- No results
- Access denied due to permissions
- Create, Delete, or Update failed
In addition, to providing users with a human-readable error messages, developers should log error messages from OCLC's web services in order to faciliate debugging. OCLC's web services provide error messages via a variety of mechanisms including HTTP status codes, SRU error codes, and error messages within the response body itself. App error logs should include all of these types of information.
HTTP 401: Application Authentication Errors
These are the types of errors that occur when your WSKey fails to authenticate appropriately. There are several possible causes:
- Invalid WSKey
- WSKey is not permitted to use the service you are making requests to
- Invalid Signature when authenticating using HMAC Pattern
- Invalid Token when authenticating using Access Tokens
HTTP 403: User Authentication and Authorization Errors
These are the types of errors that occur when a web service requires a valid user with the appropriate roles and permissions and either:
- the valid user identifier passed was not valid, or
- the user whose identifier you sent does not have the appropriate roles and permissions to perform the requested action.
HTTP 405: Method Not Supported
The HTTP method you are trying to use is not supported by the web service. Not all web services support all HTTP methods. Some web services are read-only. Some objects cannot be deleted.
HTTP 400: Invalid HTTP Body Content
- The XML or JSON you are sending does not conform to the schema that is used by the web service.
- The parameters you are sending are invalid or you are missing a required parameter. You will receive an HTTP 400 status with further information on which parameters are invalid or missing.