Error Handling, Logging and Messaging
OCLC's web services provide error messages via HTTP status codes and error messages within the response body itself. When an error happens on a POST or PUT request the web service will return both the error and the content sent in on the request.
Common errors
HTTP 400: Bad parameters
The parameters sent in the request are invalid or the request is missing a required parameter. A web service will receive an HTTP 400 status with further information on which parameters are invalid or missing.
HTTP 400: Invalid HTTP Body Content
The XML or JSON sent in the request does not conform to the schema that is used by the web service.
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:
| Cause | Error Message | Authentication Method(s) Applies to |
|---|---|---|
| No authentication information sent | Authorization Header missing | WSKeyLite, HMAC, Access Token |
| WSKey invalid | WSKey "{WSKey}" is invalid | WSKeyLite, HMAC |
| Expired WSKey | WSKey is expired | WSKeyLite, HMAC |
| Cancelled WSKey | WSKey has been cancelled | WSKeyLite, HMAC |
| Bad Signature |
Request has an invalid signature | HMAC |
| Wrong Timestamp | timestamp in request({timestamp}) is not valid; current time on server is {currentTimestamp} |
HMAC |
| Repeated nonce | nonce in request is not unique | HMAC |
| Invalid Access Token | invalid_token | Access Token |
| Expired Access Token |
{Access Token} has expired | Access Token |
HTTP 403: WSKey Authorization Issues
A 403 can be a WSKey authorization issue. This typically means the WSKey is valid but isn't for the right web service. This is the type of error that occurs when a developer tries to use a WSKey for WorldCat Search API to access WorldCat Knowledge base API.
| Cause | Error Message | Authentication Method(s) Applies to |
|---|---|---|
| Web Service Not Associated with WSkey |
Service "{serviceDisplayName}" {serviceName} not found on WSKey | WSKeyLite, HMAC |
| Web Service Expired on WSKey |
Service "{serviceDisplayName}" {serviceName} on WSKey has expired | WSKeyLite, HMAC |
| Web Service Cancelled on WSKey | Service "{serviceDisplayName}" {serviceName} on WSKey has been cancelled | WSKeyLite, HMAC |
| Web Service Not Associated with Access Token |
Access Token {Access_Token} does not have access to service {serviceName} | Access Token |
| Institution Not Associated with Access Token | Error message Varies | Access Token |
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.
| Cause | Error Message |
|---|---|
| User identifier pair (principalID and principalID) passed was not valid | Unable to retrieve user permissions due to bad request |
| User identifier does not have the appropriate roles and permissions to perform the requested action. | Missing permission : Authorization failed for user at Institution {registryID} in the context of authority id {registryID} and authority type INSTITUTION |
HTTP 403: Overlimit
The requester has reached the maximum number of requests they can make a day to the web service in question using their WSKey. Currently, WorldCat Search API and WorldCat Knowledge base API enforce this type of restriction.
HTTP 404: Not Found
The url being requested is not found. Check the documentation for the web service to make sure the URL is constructed correctly.
HTTP 405: Method Not Supported
The HTTP method of the request 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 406: Not Supported
The value that has been sent in HTTP Accept Header is not supported by the web service. Please check the web service documentation for the supported Accept header values.
HTTP 415: Unsupported Media Type
The value that has been sent in HTTP Content-Type Header is not supported by the web service. Please check the web service documentation for the supported Accept header values.
Example
<?xml version='1.0' encoding='UTF-8'?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:oclc="http://worldcat.org/xmlschemas/response"> <content type="application/xml"> <ns11:purchaseOrder xmlns:ns11="http://worldcat.org/xmlschemas/acquisitions/PurchaseOrder" xmlns:acq="http://purl.org/oclc/ontology/acquisitions/" xmlns:ns14="http://worldcat.org/xmlschemas/acquisitions/PurchaseOrderSubmission" xmlns:ns15="http://worldcat.org/xmlschemas/response" xmlns:common="http://worldcat.org/xmlschemas/common-types/CommonDataTypes" xmlns:ns9="http://worldcat.org/xmlschemas/acquisitions/Resource" xmlns:ns12="http://worldcat.org/xmlschemas/acquisitions/Copy" xmlns:ns13="http://worldcat.org/xmlschemas/acquisitions/CopyReceipt" xmlns:ns10="http://worldcat.org/xmlschemas/acquisitions/CopyConfig" xmlns:ns8="http://worldcat.org/xmlschemas/acquisitions/PurchaseOrderItem" xmlns:schema="http://schema.org/" xmlns:identity="http://worldcat.org/xmlschemas/common-types/Identity" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:gr="http://purl.org/goodrelations/v1#" xmlns:skos="http://www.w3.org/2004/02/skos/core#"> <ns11:orderName> alibris Order - 1329321767 </ns11:orderName> <ns11:vendor> <ns11:vendorId> 50f0ecab-9b4e-4da3-a1c4-e0343a1897 </ns11:vendorId> </ns11:vendor> <ns11:currency> USD </ns11:currency> <ns11:exchangeRate> 1.000000 </ns11:exchangeRate> <ns11:orderDate> 2012-03-14T10:47:38.000-04:00 </ns11:orderDate> <ns11:orderItemCount> 2 </ns11:orderItemCount> <ns11:taxCalculationMethod> EXCLUDE_ADDITIONAL_COSTS </ns11:taxCalculationMethod> <ns11:purchaseOrderState> SUBMITTED </ns11:purchaseOrderState> <ns11:totalOrderPrice> 105.75 </ns11:totalOrderPrice> <ns11:lastUpdateTime> 2012-03-14T10:47:38.000-04:00 </ns11:lastUpdateTime> <ns11:insertTime> 2012-02-15T11:02:48.000-05:00 </ns11:insertTime> <ns11:shippingAddressId> MAIN </ns11:shippingAddressId> </ns11:purchaseOrder> </content> <oclc:error> <oclc:code type="http">400</oclc:code> <oclc:message> vendorId 50f0ecab-9b4e-4da3-a1c4-e0343a1897 not found</oclc:message> </oclc:error> </entry>