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>

We are a worldwide library cooperative, owned, governed and sustained by members since 1967. Our public purpose is a statement of commitment to each other—that we will work together to improve access to the information held in libraries around the globe, and find ways to reduce costs for libraries through collaboration. Learn more »