Error Handling

Discussion

The Stack Overflow for Teams API returns an error when a request to the API is not successful. The Method Calls section explains the different error codes that can be returned from the Stack Overflow for Teams API.

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:

bad_parameter – 400

An invalid parameter was passed, this includes even "high level" parameters like key or site.

access_token_required – 401

A method that requires an access token (obtained via authentication) was called without one.

invalid_access_token – 402

An invalid access token was passed to a method.

access_denied – 403

A method which requires certain permissions was called with an access token that lacks those permissions.

no_method – 404

An attempt was made to call a method that does not exist. Note, calling methods that expect numeric ids (like /users/{ids}) with non-numeric ids can also result in this error.

key_required – 405

A method was called in a manner that requires an application key (generally, with an access token), but no key was passed.

access_token_compromised – 406

An access token is no longer believed to be secure, normally because it was used on a non-HTTPS call. The access token will be invalidated if this error is returned.

write_failed – 407

A write operation was rejected, see the returned error_message for more details.

duplicate_request – 409

A request identified by a request_id has already been run.

internal_error – 500

An unexpected error occurred in the API and has been logged.

throttle_violation – 502

An application has violated part of the rate limiting contract, so the request was terminated.

temporarily_unavailable – 503

Some or all of the API is unavailable. Applications should backoff on requests to the method invoked.

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.