Support

Sometimes even the most stable web services and elegant code decide to act up. The Developer Network team is happy to lend a hand to help get your project back on track. You can reach us through our contact form, or shoot us an email at devnet[AT]oclc.org.

How to help us help you

A little bit of information can really help speed up our troubleshooting so that we can get you an answer more quickly. If you don't have these details at hand, or aren't quite sure what it is we're talking about, send us what you can and we'll walk you through the rest.

Describe your project or goal

Are you building a table or a lamp? Tell us as much as you can about what you're trying to do:  

  • I want to create a new Purchase Order with the Acquisitions web service
  • I want to search WorldCat Search API for books about Chinese cooking held by University of Wisconsin Madison
  • I want to use the WorldCat Metadata API to set holdings on OCLC Number 319501305 for institution ID - 128807

Authentication or WSKey problems

It's best if you can send us your WSKey string. Be sure to keep your secret a secret - we really just need the key string. We can always look up your WSKey if you provide your:

  • your institution affiliation
  • associated service(s)

Request problems

Send us the HTTP request including all the headers and body information, e.g,:

GET /bib/data/319501305?holdingLibraryCode=MAIN&classificationScheme=LibraryOfCongress&
instSymbol=OCPSB&principalID=12345&principalIDNS=urn%3Aoclc%3Awms%3Ada HTTP/1.1
Host: worldcat.org
User-Agent: Platform PHP Test Client
Accept: application/atom+xml;content="application/vnd.oclc.marc21+xml" 
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 
clientId="LOAjXFWEtkA5JHrbpu2YElhMypGHXEP9Rjp2pTt4E2GwZ1Bx0RhA7YyQutyuSXX5AAjJv1aYH0FWirC6", 
timestamp="1370357606", 
nonce="3bdf237a", 
signature="dnWqDMjh3o6eriU1T4aNxOF4tzEQ6H58v5lG36ErC3c=", 
principalID="12345", 
principalIDNS="urn:oclc:wms:da"

We'd also like to see the HTTP response your received, including the HTTP status code,  message, and body of the response, e.g.,:

HTTP/1.1 403 Forbidden
Content-type: application/xml;charset=UTF-8
Content-length: 227
Date: Tue, 04 Jun 2013 15:01:24 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error xmlns="http://worldcat.org/xmlschemas/response">
    <code>403</code>
    <message>User forbidden</message>
    <detail>PrincipalID and/or PrincipalIDNS is invalid</detail>
</error>

Include these additional details where you can:

  • The WSKey you are using
  • User you performed the action as, preferrably in the form of the username
  • Date and time the request was sent
  • IP address the request was sent from
  • User-Agent your client identifies itself as (tip: consider sending a User-Agent if you aren't already - it will make your requests easier to find and debug)
  • RequestId - this is a header which the API will often return. Named x-amzn-RequestId  

Your code

This is optional, but it can really be helpful for us to see your code. Your best bets are posting it to GitHub as a GIST (https://gist.github.com/) or directing us to a code repository on GitHub. This will make it simple for us to do a quick review. While we aren’t experts in every language we do have experience working with several (PHP, Ruby, Java, Javascript) and seeing your code may help us debug the problem with you.

How to help yourself

We have reason to believe some of you are DIY-ers who might just want to check some things on your own. Here are some ideas to get you started.

Utilize handy resources

  • Check our FAQ page regularly - we'll keep it well fed and growing
  • Use the API Documentation or PostMan to do isolated tests of messages and responses
  • It never hurts to double check the documentation
  • Query your peers via the Community Center

Check for common errors

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
  • Invalid Signature when authenticating using HMAC Pattern
  • Invalid Token when authenticating using Access Tokens
HTTP Status Code
Error Message Cause
401 WSKey '{wskey}' is invalid Invalid Wskey
401 WSKey is expired WSKey Expired
403 WSKey has been canceled WSkey Cancelled
401 request has invalid signature ({signature}) Signature improperly built
401 timestamp in request({timestamp}) is not valid; current time on server is {currentTime} Timestamp is incorrect
400 required parameter 'scope' is missing or blank Scope not sent when requesting Access token

Application Authorization Errors

These are the typs of errors that occur when the WSkey you are using authenticates appropriately but isn't authorized to do the action.

  • WSKey is not permitted to use the service you are making requests to
  • WSKey is not permitted to interact with the institution's data being requested
HTTP Status Code
Error Message
Cause
403 Invalid scope(s): {scope} ({service name}) [Not on key] Service not on WSKey
403 Invalid scope(s): {scope} ({service name} [Canceled] Canceled Service
403 Invalid scope(s): {scope} ({service name} [Expired] Expired Service
403 clientId {{Wskey}} doesn't have access to contextIntitutionId {{institution_id}} Institution data being requested is not associated with WSKey

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 Status Code
Error Message Cause
403 Invalid user User passed is not valid
403 Missing permission User passed doesn't have the appropriate permissions

Request Errors - General

HTTP Status Code
Error Message Cause
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.
406
Not Acceptable
The HTTP Accept header (serialization) that has been requested is not available from this web service

Request Errors - Writing Data

HTTP Status Code
Error Message Cause
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.
409 Conflict You aren't using the most recent copy of the data to perform an update.
412 Precondition Failed A precondition sent as an HTTP header isn't true. For example, a PUT request with an If-Match header set to the value of an E-Tag would return 412 if a resource had been updated since it was last retrieved.
415 Unsupported Media Type The HTTP Content-Type header (serialization) sent for writing data is not supported by this web service