I am building a service which acts as a proxy to third party data providers for the end-user. My service uses tokens for authorization and if the user does not have a valid token it responds with 401 Unauthorized. If the token is valid but access to the resource is denied my service responds with 403 Forbidden.

The service fetches data from third party data providers. These data providers use the same response codes (401/403). When such a token has expired, the end-user must enter their credentials to that service again so that my service can request new tokens from the third party providers.

If I just forward the 401/403 from the third party data provider to my end-user, they will not be able to know if authorization failed towards my service or the third party. The frameworks I am using does not allow me to change the message nor send a body with the response.

I have been pondering which status code I can use and thought of 511 Network Authentication Required. This code is used by "proxies" and my service does act as a proxy, although perhaps not in the way a "normal" network proxy does.

Would 511 be a reasonable status code to use or is there something better?

  • Are you using oauth or some other token mechanism? Dec 21, 2017 at 16:37
  • @JimCulbert Yes, both my proxy acting service and the third party data provider use OAuth in different flavors. They are completely separate though so no sharing of data between IdP's.
    – span
    Dec 22, 2017 at 19:05
  • Why don't you just complet the response with an specific message? In your specific escenario, I don't see why it should be returned as a server error (5xx). 5xx means: "something is worng in the server-side. Stay tunned". Somehow I think this's not true here. 401/403 + an specific message for each scenario would be enough.
    – Laiv
    Jan 3, 2018 at 21:34
  • Thanks @Laiv, unfortunately the frameworks I am using does not allow me to change the message nor send a body with the response.
    – span
    Jan 4, 2018 at 7:46
  • Is there any way for devs to extend the framework components and behavior?
    – Laiv
    Jan 4, 2018 at 7:51

1 Answer 1


I don't think the 511 code is appropriate for what you describe. The primary use case for that code is a "captive portal" like the holding pen you get put in at a coffee shop before accepting terms of use and/or logging in at the coffee shop web page.

Your use is pretty much what oauth is designed to handle; a client application interacting with resource servers on behalf of a resource owner.

There are two authentication points, initial authentication/access token acquisition and refresh token acquisition. Presumably, you have figured out how to authenticate the user on first access to the resource server(s).

When the access token expires, you are supposed to use a refresh token to request a new access token (on behalf of the user) so the current and future requests can proceed without resource owner interaction. If the authentication servers for the resources that you are accessing are providing refresh tokens, you should hold on to these and use these to acquire new access tokens when requests fail (and not send a 401 back).

Authorization servers are not required to send refresh tokens. In that case, a 401 from a resource server should trigger the initial authorization flow again (to retrieve a new access token). Normally, that's a 302 redirect to the authorization server with the client_id, scope, etc. I know you said that you cannot modify the response body but, since you're considering the 511 response code, you must be able to issue a 302.

I would suggest, if you are in fact using oauth for your own app as well, that you never issue a 401 for an expired token but always either use the refresh token to regain access to the resource server (if available) or redirect to the appropriate authorization endpoint to continue the request.

  • Thank you, I follow your reasoning and pretty much agree. I thought of using 302 but after reading the spec it seemed like a "hack" since, "The 302 (Found) status code indicates that the target resource resides temporarily under a different URI", and the URI to the resource is actually the same. Perhaps it is less of a hack then 511 though. Unfortunately I am not fully in control of the authorization reponses to my app either (oh how Enterprise coding is fun).
    – span
    Jan 3, 2018 at 18:43

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.