RFC 2616 says 502 means: "The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request."
What exactly counts as an invalid response? Does this include something like a 500 from the upstream server?
Imagine that you have implemented and API that aggregates responses from a couple of third party servers. E.g. you have an application that if asked for info about lol#lol.com user will return all the public data about this user from FB, TW and G+.
More or less your API acts as a proxy server. Now if one of these requests fails you have a choice what will be returned to the client. If you want to be explicit about how your application works you can return 502 Bad Gateway along with message: Sorry, request to FB failed for whatever reason and that's all. But you can also hide the implementation details and return a e.g. 409 Conflict response along with details: Have no info about the user's FB activity.
In this particular example 207 Multi Status would be also very useful.
Related
I have a client coded in JavaScript. This client calls an API method on my server which is coded in PHP. This API method is "GET /user" and could return a 200 status or a 204 status.
The 200 status is intended for authenticated users.
The 204 status is intended for guest users and can in the future become a 200 with information about these guest users (like frontend autorizations).
I had a confrontation with developers who think my API should return a 401 status in case the user is a guest. But I said there was no client error since the client just ask for the authentication state + some information about the non guest user.
So my question is pretty simple: is there a missconception in my API ?
I would suggest neither.
Take a look at section 10 of the HTTP/1.1 RFC and see if you can match your response code with what is being returned.
If you are returning data from GET /users (regardless of authenticated client or guest) then 204 No Content is not appropriate:
The 204 response MUST NOT include a message-body, and thus is always terminated by the first empty line after the header fields.
A 401 Unauthorized is only appropriate if the method being called is only accessible to authenticated clients. You are essentially telling the client that they have done something they are not allowed to.
If both an authenticated user and a guest user are expected clients of your API I would suggest returning a 200 OK to both clients and have any differentiation made clear in the returned body itself.
I totally agree with the answer of #Johnson. Do not change the meaning of the status codes. If it is a valid request, you should respond with 200.
The problem here is that the endpoint you define is not a resource-oriented endpoint (problem = REST API design guidelines are not really applicable as they are mostly focused on resource oriented APIs). /user in your case seems to return a state rather than a resource. 401 is good for telling the client that it is not authenticated and thus cannot fetch the requested resource.
In your case it is just an informative endpoint for the client to check its login state and both states (logged in and not logged in) are successful answers from a technical point of view and thus require a 200 response. To tell the client the login state you should use the response body, not the status code.
Lets say I have an API endpoint that executes some business operation which can result in many different failures that are not connected directly to the request.
The request is correctly formed and I cannot return 4xx failures, but the logic of the application dictates that I return different error messages.
Now I want the client to be able to differentiate these error messages so that different actions can be taken depending on the code. I can return a custom JSON like this e.g.
{
"code": 15,
"message": "Some business error has occurred"
}
Now the question is which HTTP status code should I use for such occasions if no standard code like Conflict or NotFound makes sense.
It seems that 500 InternalServerError is logical, but then how can I additionally flag that this cannot be retried, should it be just documented that given status codes is not possible to retry so one can retry if you don't get one of those?
Consult RFC 7231:
503 Service Unavailable looks like a potential candidate, but the RFC mentions that this is supposed to represent a problem "which will likely be alleviated after some delay." This would indicate to a client that it could try the same call later, maybe after business hours or on the weekend. This is not what you want.
501 Not Implemented could be possible, but the RFC mentions "This
is the appropriate response when the server does not recognize the
request method and is not capable of supporting it for any resource. A 501 response is cacheable by default;" This does not appear to be the case here - the HTTP method itself was presumably valid - the failure here seems to be happening at the business rules layer (e.g. sending in an account number that is not in the database), rather than an HTTP method (GET, POST, etc.) that you never got around to implementing.
That leaves the last serious candidate,
500 Internal Server Error
The 500 (Internal Server Error) status code indicates that the server
encountered an unexpected condition that prevented it from fulfilling
the request.
This is the error code that is normally used for generic "an exception occurred in the app" situations. 500 is the best choice.
As to how to distinguish this from a "temporal internal trouble" error, you can include this as part of the HTTP body - just make sure that your client can parse out the custom codes!
I have seen the list of all HTTP status codes.
However to me it looks like there is no code for "email not verified" (used for authentication/authorization).
Did you ever had the same "problem"? What HTTP status code did you use?
I guess it should be a code starting with a 4 as it's a "client error".
The 4xx class of status code is intended for situations in which the client seems to have erred:
6.5. Client Error 4xx
The 4xx (Client Error) class of status code indicates that the client
seems to have erred. Except when responding to a HEAD request, the
server SHOULD send a representation containing an explanation of the
error situation, and whether it is a temporary or permanent
condition. These status codes are applicable to any request method.
User agents SHOULD display any included representation to the user.
For authentication and authorization, 401 and 403 are the proper status codes to be used, respectively. Regardless of the status code, you should always describe that reason of the error in the response payload.
401 Unauthorized
Use this status code for problems with HTTP authentication, that is, invalid credentials.
3.1. 401 Unauthorized
The 401 (Unauthorized) status code indicates that the request has not
been applied because it lacks valid authentication credentials for
the target resource. The server generating a 401 response MUST send
a WWW-Authenticate header field containing at least one
challenge applicable to the target resource.
If the request included authentication credentials, then the 401
response indicates that authorization has been refused for those
credentials. The user agent MAY repeat the request with a new or
replaced Authorization header field. If the 401
response contains the same challenge as the prior response, and the
user agent has already attempted authentication at least once, then
the user agent SHOULD present the enclosed representation to the
user, since it usually contains relevant diagnostic information.
403 Forbidden
Use this status code for problems with authorization, that is, the credentials are valid but they are insufficient to grant access.
6.5.3. 403 Forbidden
The 403 (Forbidden) status code indicates that the server understood
the request but refuses to authorize it. A server that wishes to
make public why the request has been forbidden can describe that
reason in the response payload (if any).
If authentication credentials were provided in the request, the
server considers them insufficient to grant access. The client
SHOULD NOT automatically repeat the request with the same
credentials. The client MAY repeat the request with new or different
credentials. However, a request might be forbidden for reasons
unrelated to the credentials. [...]
While CodeCaster has provided a very definitive answer as a comment, that which is correct is sometimes not appropriate.
Firstly, you'll see there is no mention of email addresses in the specs. Similarly there is no mention of shoe sizes, model railway gauges, breeds of dogs nor many other things. It is not relevant to HTTP. This is just a data item.
You seem to have some state associated with this data item which you use for authentication purposes - but don't provide any explanation of that state nor how it is applied. I assume that you mean that the "not verified" state means that the only association between the data item and the user interacting with your site is an assertion of the user. And further that you do not allow the user to authenticate with this as a token.
It may seem I'm being pedantic here - but there are other, valid interpretations of "email not verified". You should have provided more information in your question.
There's another gap in your story: which request are we taking about here? Again, I'll take the liberty of assuming that the request is an attempt to authenticate.
In this case, there is nothing intrinsically wrong with the request. There is nothing intrinsically wrong with the client. There is nothing intrinsically wrong at the server. Not permitting the user to authenticate is a policy decision based on the data.
Another critical bit of information missing from your question is what is actually making the request. If its a form sent by a browser, then returning anything other than a 200 OK (or 204, or a redirect to a 200) to MSIE will, by default, cause the browser to display an internal message and not the content you send.
OTOH if the client is an application running on the users device, or an Ajax request, then you control the API and can define your own semantics. If you want to return a 692 status code to represent this condition, then you can return a 692 error code. You can even inject your own headers in the response (by convention these should begin with 'X-').
In the defined state the authentication fails. But returning a 401 response will prompt a browser to attempt HTTP authentication - which doesn't address the issue.
IMHO, the nearest existing code is 403 or 422. But based on the information you've supplied I can't say if thats what you should be using.
Some hours my web site's server has too much load.
Which HTTP status code should I send to the Googlebot that visits my website?
Is "269 Call Back Later" this suitable for this case, or 503 Service Unavailable or do you have any more suggestions?
503 means the service is temporarily unavailable so it is appropriate to use while the server is overloaded. http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
The Wikipedia article defines 269 as the initial response for a request that must be processed asynchronously. 269 means the request added something to the server's "queue" of things to do and the server will have a response available as soon as possible, whereas 503 means the server will not "remember" the request.
I've never heard of 269, though, and the first Google result for it is this question, followed by the Wikipedia article.
Another option is a 429 - Too Many Requests response.
Defined in RFC6585 - https://www.rfc-editor.org/rfc/rfc6585#section-4
The spec does not define how the origin server identifies the user, nor how it counts requests.
For example, an origin server that is limiting request rates can do so based upon counts of requests on a per-resource basis, across the entire server, or even among a set of servers.
Likewise, it might identify the user by its authentication credentials, or a stateful cookie.
Also see the Retry-After header in the response.
Scenario:
A POST request is sent to process an order that will result in data retrieval from an external datasource.
There are three possible results:
The datasource returned data for the request
No data was available for the request (this is viewed as an error)
The datasource couldn't be accessed (may be down for maintenance)
An obvious response for 1 is 200: OK or 201: Created (an entity is created from this request).
What status codes would be appropriate for 2 and 3?
Status codes I have considered:
503: Service Unavailable when datasource is down
500: Internal Server Error when datasource is down
502: Bad Gateway when "no data available"
404: Not Found when "no data available"
403: Forbidden when "no data available"
412: Precondition Failed when "no data available"
2) Looking back at this, I agree it should probably be either a 204 No Content or maybe a 200 with a body indicating no records or resources could be found depending on the structure returned.
404's are generally used when the resource URI doesn't exist or a resource in the URI is not found in the case of a restful service.
3) 503 Service Unavailable
The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response.
Note: The existence of the 503 status code does not imply that a
server must use it when becoming overloaded. Some servers may wish
to simply refuse the connection.
3) I agree with 503 for this
2) Frankly I think a good argument could be made for using 204 in case 2 You can include metainfo in the header to indicate specifically what 'went wrong'. It really depends on how much you consider this case to be 'an error' at the API level.
If the API itself is functioning as intended, and the request was to a valid endpoint, by an authenticated and authorized user and did not cause the server to malfunction, then very few of the 400 or 500 series errors would really seem to apply.
for example, 404 usually means the URI you called does not exist, if it does exist, then using that code is misleading at least IMHO
**10.2.5 204 No Content**
The server has fulfilled the request but does not need to return an
entity-body, and might want to return updated metainformation. The
response MAY include new or updated metainformation in the form of
entity-headers, which if present SHOULD be associated with the
requested variant.
If the client is a user agent, it SHOULD NOT change its document view
from that which caused the request to be sent. This response is
primarily intended to allow input for actions to take place without
causing a change to the user agent's active document view, although
any new or updated metainformation SHOULD be applied to the document
currently in the user agent's active view.
The 204 response MUST NOT include a message-body, and thus is always
terminated by the first empty line after the header fields.
HTTP 404 - With your own error message like "No data found".
Twitter uses 404.
Reference: https://developer.twitter.com/en/docs/basics/response-codes.html
The datasource returned data for the request
200: OK/201: CREATED
Because everything is working as expected
No data was available for the request (this is viewed as an error)
400: BAD REQUEST
The request was invalid or cannot be otherwise served. An accompanying error message will explain further inside the body.like:
HTTP 400
{
response: null,
code: "USER_101", //should be used customized error codes here
error: "User details not found"
}
The datasource couldn't be accessed (may be down for maintenance)
404: Resource/URI NOT FOUND
The URI requested or resource is invalid
Like: https://www.lipsum.com/list-page
**/list-page** is not defined/found
Find here most frequently used status codes:
200 – OK
Everything is working, The resource has been fetched and is transmitted in the message body.
201 – CREATED
A new resource has been created
204 – NO CONTENT
The resource was successfully deleted, no response body
304 – NOT MODIFIED
This is used for caching purposes. It tells the client that the response has not been modified, so the client can continue to use the same cached version of the response.
400 – BAD REQUEST
The request was invalid or cannot be served. The exact error should be explained in the error payload.
401 – UNAUTHORIZED
The request requires user authentication.
403 – FORBIDDEN
The server understood the request but is refusing it or the access is not allowed.
404 – NOT FOUND
There is no resource behind the URI.
500 – INTERNAL SERVER ERROR API
If an error occurs in the global catch blog, the stack trace should be logged and not returned as a response.
In my opinion the best way to handle this is with a 200 no result object.
Why?
You have a response that you can do something with without a lot of trouble. I searched, everything worked correctly but there wasn't anything in the database to give a result. Therefore, result = null and a message explaining as much. If something found this in the network calls it is not a security risk.
If you are concerned with a security risk then a 204 is probably the best approach.
res.status(200).send({
result: null,
message: 'No result'
});