Take the 2-minute tour ×

I'm writing a REST-ish API service the provides the ability to interact with the end user's data in other 3rd party services (themselves REST APIs) via OAuth. A common example might be publishing data from my service to a third-party service such as Facebook or Twitter.

Suppose, for example, I perform an OAuth dance with the end user and Facebook, resulting in some short-term access token that my service can use to interact with the user's Facebook account. If that access token expires and the user attempts to use my service to publish to Facebook, what sort of error do I return to the user?

401 doesn't seem quite right to me; it seems that 401 would apply to the user's auth state with MY service. 403 seems much more appropriate, but also quite generic.

share|improve this question

3 Answers 3

up vote 3 down vote accepted

401 is the way to go. Two excerpts from the RFC2616 which defines the HTTP protocol:

Section 10.4.2 (about 401):


This seems to be appropriate for expired tokens. There are authentication credentials, but they're refused, so the user agent must re-authenticate.

Section 10.4.4 (about 403):


This should be used when the resource can't be accessed despite the user credentials. Could be a website/API that works only on US being hit by a asian IP or a webpage that has been declared harmful and was deactivated (so the content WAS found, but the server is denying serving it).

On OAuth2, the recommended workflow depends on how the token is being passed. If passed by the Authorization header, the server may return a 401. When passed via query string parameter, the most appropriate response is a 400 Bad Request (unfortunately, the most generic one HTTP has). This is defined by section 5.2 of the OAuth2 spec http://tools.ietf.org/html/draft-ietf-oauth-v2-26

share|improve this answer
Thanks. Is there anything in HTTP that describes authorization as a "scoped", multi-domain, or otherwise non-binary state? One reason 401 rubs me the wrong way is that we tend to view it as an error with respect to the service issuing it, whereas in the example I described, the auth problem is really external to the service delivering the error. A user may be properly authed with my service, but not authed with the 3rd party. It seems important to have a clear distinction between these two cases. This may be a case where HTTP doesn't provide a satisfying vocabulary for the problem domain. –  Jeff Lee May 22 '12 at 18:20
401 should be used only for OAuth related errors, which is really only a subset of possible errors when creating an API. –  Jon Nylander May 23 '12 at 11:13

There's nothing wrong with being generic, and it sounds like a 403 status would be relevant - there is nothing stopping you from providing a more human readable version that elaborates in a bit more detail why.

share|improve this answer
Yeah, although the RFC quoted by @alganet does seem to imply that 403 might be the wrong thing to do. Of course, you could interpret the "DO NOT REPEAT" injunction to mean "DO NOT REPEAT WITHOUT FIRST RE-AUTHENTICATING", since in this case the authentication represents a state that is external to the request itself. –  Jeff Lee May 22 '12 at 18:22

I think the following is a comprehensive list if you have some level of ambition when it comes to error responses.

400 Bad Request

For requests that are malformed, for example if a parameter requires an int between 0-9 and 11 has been sent. You can return this, and in the response body specify parameter x requires a value between 0 and 9

401 Unauthorized

Used only for authorization issues. The signature may be wrong, the nonce may have been used before, the timestamp that was sent is not within an acceptable time window, again, use the response body to specify more exactly why you respond with this. For the sake of clarify use this only for OAuth related errors.

403 Forbidden

Expressly to signify that an operation that is well formed, and authorized, is not possible at all (either right now, or ever). Take for example if a resource has been locked for editing by another user: use the response body to say something along the lines of Another person is editing this right now, you'll have to wait mmkay?.

403 Forbidden can also have to do with trying to reach resources. Say for example that a user has access to a resource /resource/101212/properties.json but not to /resource/999/properties.json, then you can simply state: Forbidden due to access rights in the response body.

404 Not Found

The requested resource does not exist. Or the URL simply does not successfully map to an API in your service. Specify in response body.

405 Method Not Allowed

This is to represent that the API can not be called with for example GET but another method must be used. When this is returned also you MUST return the extra response header Allow: POST, PUT, etc.

share|improve this answer

Your Answer


