I have a RESTful web service which requires an end-user license agreement (EULA) to be accepted before it can be used.
Which HTTP status code would be most appropriate for the web service to return if the EULA has not (yet) been accepted?
Currently I see the following possibilities (my current favorite in bold):
403 Forbidden
412 Precondition Failed
417 Expectation Failed
423 Locked
428 Precondition Required#
451 Unavailable For Legal Reasons
As suggested by CodeCaster I went to w3.org and looked at the definitions of HTTP Status Codes in RFC2616. I found Status Code 403 to be most appropriate:
10.4.4 403 Forbidden
The server understood the request, but is refusing to fulfill it.
Authorization will not help and the request SHOULD NOT be repeated. If
the request method was not HEAD and the server wishes to make public
why the request has not been fulfilled, it SHOULD describe the reason
for the refusal in the entity. If the server does not wish to make
this information available to the client, the status code 404 (Not
Found) can be used instead.
401 Unauthorized
As George Clooney would say: "What else!". You authorize people accessing your service after they agree with the EULA. They didn't do that, so they aren't authorized (to be compliant with the RFC, authenticating and retrying clients would have to include the WWW-Authenticate header, but you must somehow provide that information anyway, and this way is just as good as any other way).
On a different thought, you could just as well return 301 pointing to the agreement page. The reasoning behind that approach would be that 4xx codes signal an error condition. However, not having agreed to the EULA yet is (other than a failed authentication) not really an error condition.
It's preventing the service from being used, yes... but everything is "working fine".
Messages should be self explanatory, my vote also for 412 Precondition Failed.
Related
If user has to upload files and confirm them via API endpoint call, what status code should be returned if user calls the confirm endpoint but has not uploaded all of the required files?
400 doesn't seem to be right because there is nothing wrong with the request parameters.
403 doesn't seem to be right because there is nothing wrong with credentials.
The 403 (Forbidden) status code indicates that the server understood the request but refuses to fulfill it.... a request might be forbidden for reasons unrelated to the credentials. -- HTTP Semantics
Keep in mind that status codes are metadata in the transfer of documents over a network domain; they tell HTTP components how to interpret the fields and body in the HTTP response.
See also Mark Nottingham on the generic semantics of status codes.
I don't think it is as good a choice, but it 409 conflict is an alternative that is probably harmless?
The 409 (Conflict) status code indicates that the request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request. -- HTTP Semantics
We have a mobile app which sends its version in an HTTP header when sending API requests.
On the backend we are trying to refuse requests from old unsupported mobile apps.
What HTTP status code is appropriate for this case?
P.S. Please let's not start a discussion about API versioning.
426 (Upgrade Required) seems like a valid candidate. So are: 412(Precondition Failed), 417(Expectation Failed). Purely depends on how you interpret it in your application
Status codes are meant to describe the result of the server's attempt to understand and satisfy the client's corresponding request.
However, it's unlikely you'll find specific status codes for each situation. So, assuming it's a client error, you could go with 400:
6.5.1. 400 Bad Request
The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
And, as HTTP status codes are not always sufficient to convey enough information about an error to be helpful, ensure you return details about the error on the payload.
You could have a look at the RFC 7807, as it defines simple JSON and XML document formats to inform the client about a problem in a HTTP API. It's a great start point for reporting errors in your API. It also defines the application/problem+json and application/problem+xml media types.
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).
Let's say we have an online shop and receive a valid request of updating some order.
The request is valid by itself, but let's say that the order has an expiration time, and it has already expired, so this request is unprocessable in fact.
I doubt if it is a kind of validation error or not. Because, as I stated above, the request itself is valid; and a request sender might not know that order has already expired.
What's an appropriate HTTP status code to return by a REST API service for such a situation?
Warning: Due to the general requirements for the product, it should be some of 4XX error codes!
UPD: More information: this putative "order" still exists, even being expired. It is possible to retrieve it, but it is not possible to operate it anymore. That's why the code 404 (for example) is not appropriate.
My own version:
I think that for such situation the 410 status code is most appropriate:
The 410 response is primarily intended to assist the task of web
maintenance by notifying the recipient that the resource is
intentionally unavailable and that the server owners desire that
remote links to that resource be removed. Such an event is common
for limited-time, promotional services and for resources belonging to
individuals no longer associated with the origin server's site. It
is not necessary to mark all permanently unavailable resources as
"gone" or to keep the mark for any length of time -- that is left to
the discretion of the server owner.
https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html:
The requested resource is no longer available at the server and no
forwarding address is known. This condition is expected to be
considered permanent. Clients with link editing capabilities SHOULD
delete references to the Request-URI after user approval. If the
server does not know, or has no facility to determine, whether or not
the condition is permanent, the status code 404 (Not Found) SHOULD be
used instead. This response is cacheable unless indicated otherwise
I'll say that 400 fits better than 410.
IMO 410 (Gone) doesn't fit because the resource is not gone. It's still there, simply in kind of a final (in this case expired) state.
400 means BadRequest. Per my interpretation, trying to UPDATE something, that is not updatable (trying to update expired item) is a BadRequest.
I believe, that 400 is not only for badly formatted requests, but also for requests that does not meet internal business logic validation (in this case, not updating an expired item, is an internal business logic).
Use 410 Gone.
The target resource is no longer available at the origin server and that this condition is likely to be permanent.
I would choose one of these:
400 - Bad request
410 - Gone
from : https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
I am using HTTP HEAD request for checking is a userlogin name is available or not. Now I am returning a 200 OK response if the user login name is available, What do I return if login is not available? Should it be 409 or 403 or 410 (Gone).
I believe that 409 makes the most sense.
The request could not be completed due to a conflict (username already taken).
This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.
Your response body SHOULD include enough information for the user to understand the username is already taken.
Edit
The 410 Gone response should only be used if requested resource is no longer available at the server and no forwarding address is known. These are for situations where the request-URI is not available temporarily. Some suggest to just use 404 if you think the URI will be down for long periods.
The 403 indicates a fundamental access problem. It is more difficult to resolve because the HTTP protocol allows the Web server to give this response without providing any reason at all. This is equivalent to a blanket 'NO' by the Web server - with no further discussion allowed.
What is the correct HTTP status code to return when a server is having issues communicating with an external API?
Say a client sends a valid request to my server A, A then queries server B's API in order to do something. However B's API is currently throwing 500's or is somehow unreachable, what status code should A return to the client? A 5* error doesn't seem correct because server A is functioning as it should, and a 4* error doesn't seem correct because the client is sending a valid request to A.
Did you consider status codes 502 and 504?
502 – The server while acting as a gateway or a proxy,
received an invalid response from the upstream server it accessed
in attempting to fulfill the request.
504 – The server, while acting as a gateway or proxy,
did not receive a timely response from the upstream server
specified by the URI (e.g. HTTP, FTP, LDAP)
or some other auxiliary server (e.g. DNS) it needed to access
in attempting to complete the request.
Of course, this would require a broad interpretation of "gateway" (implementation of interface A requiring a call to interface B), applied to the application layer. But this could be a nice way to say : "I cannot answer but it's not my fault nor yours".
Since the API relies on something that is not available, its service is unavailable as well.
I would think that the status code 503: Service Unavailable is the best fit for your situation. From the RFC description:
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.
Granted, the description implies that this status code should be applied for errors on the server itself (and not to signal a problem with an external dependency). However, this is the best fit within the RFC status codes, and I wouldn't suggest using any custom status codes so anyone can understand them.
Alternatively, if your API supports a way of communicating errors (e.g. to tell the user that the ID he supplied is incorrect) you may be able to use this method to tell the user that the dependency is unavailable. This might be a little friendlier and might avoid some bug searching on the user's side, since at least some of the users won't be familiar with any status codes besides 403, 404 and maybe 500, depending on your audience.
You can refer this link.
HTTP Status 424 or 500 for error on external dependency
503 Service Unavailable looks perfect for the situation.
It's been a while that this question was asked.
Faced similar situation today. After exploring a bit, to me it makes more sense to send 424 FAILED_DEPENDENCY.