Error Handling
Discussion
There are two classes of errors that can be returned by the API, those encountered during an authentication flow and those encountered during a method call.
Authentication
Errors generated from the authentication flow are discussed in the authentication documentation and are defined by the OAuth 2.0 specification.
Method Calls
Errors from method calls are reported on the common response wrapper object in the
error_id
, error_message
, and error_name
fields. Note that while it is possible to
construct a filter that excludes these fields, in the face of an error there is no guarantee that filters will be applied.
The HTTP code will be 400 (Bad Request) for all errors unless the method was called via JSONP, in which case even an error will be returned as a 200 (OK). This is necessary, as a 400 code will generally prevent a client side app from reading the remaining error details if the call was via JSONP. In rare cases (typically dealing with network wide maintenance or hardware failure), errors may occur in processing a request before the API determines whether a request is via JSONP; in these cases a 400 (Bad Request) is returned.
Possible errors:
key
or site
.
For testing purposes, the /errors/{id} will simulate any error given its code. For introspection purposes, the /errors method will return a list of all possible errors the API may return.