Error Handling and Error Codes

The API response can indicate an error condition, such as:

• The information requested doesn't exist. For example, if a given URL has not been submitted to Digg, then a request for such stories will trigger an error response, to let the caller know that no such story exists.

• The API request is invalid. For example, an argument was misspelled or has a value that violates documented constraints.

• An internal error occurred. Generally, there's nothing the caller can do to correct such errors. They are automatically reported to us, so we can investigate.

An error response includes a mnemonic code and a human-readable message. Programmers should rely on the code to detect and handle errors, because the message may change over time or appear in various national languages.

When possible, the error response is provided in the content type specified in the request. If the requested content type cannot be determined, the error response will use the XML content type.

The error response for each content type is, we hope, useful in context:

• XML: An XML document with a single "error" element with "code" and "message" attributes.

• JSON: A JSON-encoded object with "code" and "message" properties.

• Javascript: A Javascript call to the callback function, passing an object with "code" and "message" properties. For errors involving the callback argument itself, an alert() statement is returned.

• PHP: A serialized PHP object of class DiggAPIError with "code" and "message" properties.

The error response is returned with an appropriate HTTP status code:

HTTP Status Codes

In addition to the error code and message described above, the Digg API returns an appropriate HTTP status code. Note that when the Javascript response type is specified, the status is always 200, because an error status prevents Javascript from running in many environments.

403 Forbidden

HTTP status 403 Forbidden is returned when the request is not valid.

Example:

GET /stories?appkey=example&count=500 HTTP/1.1
Host: services.digg.com
Accept: */*

...
HTTP/1.1 403 Forbidden
Content-Type: text/xml;charset=UTF-8
Content-Length: 71

<error code="727321514" message="count may not be greater than 100" />

404 Not Found

HTTP status 404 Not Found is used when the requested data does not exist, or when an endpoint is requested which does not exist.

Example:

GET /story/10000000?appkey=example&type=javascript&callback=example HTTP/1.1
Host: services.digg.com
Accept: */*

...
HTTP/1.1 404 Not Found
Content-Type: text/javascript;charset=UTF-8
Content-Length: 15

throw 'Not found'

500 Internal Server Error

HTTP status 500 Internal Server Error is used when an internal error occurs.

Example:

GET /stories/popular?appkey=example&type=json HTTP/1.1
Host: services.digg.com
Accept: */*

...
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 15

{"error":"Internal error"}

Error Codes and Messages

The API reports errors with both a code and a message. The code is more useful in programs, because the message may in future vary by national language.

Here is a list of all of the error codes used by the API. (Note that this list is created through a Javascript call to the List Errors endpoint.)

 Create your own business wiki!Support CommunityPublic, Platinum wiki Privacy Policy RSS