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).
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
Our image board allows users to upload images by copy-pasting URLs. A client app sends a POST request to our API with an image URL given in the request body. Our web service receives the POST request and handles it by downloading the image from the given URL by using a server-side HTTP client (request in our case).
In successful case, the service finds the image, downloads it, and stores it to the server. The service returns HTTP 200 to the client.
Now, what if the image cannot be found? What if the download attempt results in HTTP 404? What HTTP error code should we use to response to the client?
HTTP 400 Bad Request is not applicable because the request was well-formed and all parameters were valid.
HTTP 404 Not Found is not applicable because the request URL was found and served although the image URL was not.
HTTP 502 Bad Gateway does not feel right either because there is nothing wrong with our server or the upstream server (the server of the source image). The user just happened to type in an image URL that does not exist.
Any experience on the matter? Which error code is the most correct?
First of all you should decide if this is a client error (4xx) or server error (5xx). From what you describe, it feels more like a client error. The client has requested the creation of a resource from another resource (the image URL) which does not exist.
There is no perfect match for this scenario, although one could make a case for each of the 2 following response codes:
HTTP 409 Conflict: From the RFC:
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...
This applies to your case if you consider the target resource to be in a bad state (image not found). If someone provides an image at the specified URL, that effectively transitions your resource to a valid state.
This is also a good match because, as the RFC states, this code implies the user might be able to resolve the conflict (in your case the user would correct this by posting the image to the specified URL).
HTTP 424 Failed Dependency: From the RFC:
The 424 (Failed Dependency) status code means that the method could
not be performed on the resource because the requested action depended
on another action and that action failed...
This applies to your case in that "the requested action depended on another action and that action failed". The dependent action is the posting of an image to the other URL. What you have described is a case where that dependent action either failed or did not happen (which could also be called a failure).
Since the API determines on something that is not available, its service is unavailable as well.
The status code 503: Service Unavailable is the best fit for your situation.
According to 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.
Alternatively, if your API supports a way of communicating errors (e.g. to tell the user that the information he submitted is incorrect) you may be able to use this method to tell the user that the external resource is unavailable. This might be a little friendlier and might avoid some error raises on the user's side.
Since the client app sends POST requests to your API server the response codes should be generated according to the received server in your case this is your API server.
If the server has received correct information from the client app and server determines the request as valid, it should return apropriate code with proper JSON or header based error messages.
http error codes were conceived assuming that all pages possibly served were stored locally, one way or another.
Your scenario does not match that assumption and it should therefore not come as a surprise that you don't find codes that fit your bill properly.
Your "not found" scenario is in fact an application error and you should notify your user of the situation by providing an error message on the form where he entered the URL (or return a fully dedicated error page or some such). Or choose an http error nonetheless and accept the notion that it will be a poor fit no matter what.
Now, what if the image cannot be found? What if the download attempt results in HTTP 404? What HTTP error code should we use to response to the client?
The main thing to keep in mind: you are trying to fool the client into thinking that you are a web site - just a dumb document store which might respond to some content editing messages.
For the client, the primary means of communication is the body of the response. See RFC 7231
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.
The status code is meta-data: aimed at giving the generic components participating in the exchange a chance to know what is going on (examples: the web browser doesn't need to know what page you are asking for to recognize a redirection response returned by the server, the web browser asking for credentials when it receives a 401 unauthorized response, web caches invalidating entries, or not, depending on the status code returned by the response).
HTTP 400 Bad Request is not applicable because the request was well-formed and all parameters were valid.
Yes, that's exactly right.
I would probably use 500 Internal Server Error, on the grounds that there's nothing wrong with the _document that the server received, the problems are all involved in the side effects of the server's implementation.
A different approach you might consider: 202 Accepted. Roughly translated "I got your message, I understood your message, and I'll get around to it later." If you don't need the side effects to be synchronous, you can defer judgment. That allows you to do things like applying a retry strategy.
The representation sent with this response ought to describe the request's current status and point to (or embed) a status monitor that can provide the user with an estimate of when the request will be fulfilled.
"I'll get to it later; if you want to know how it is going, go ask him -->"
Because 202 is a non-error status code, its effect on caches is different from those of a 4xx or 5xx. If you are already thinking ahead about caching, you'll want to the implications of that in mind.
I have read this:
What is the appropriate HTTP status code response for a general unsuccessful request (not an error)?
I understand the principles but using HTTP response code to indicate RESTful API service status of a business logic thing seems ambiguous, repetitive and confusing me.
Solely taking about HTTP response code, a 403 may indicates the user not having enough privilege to use the RESTful service, or just don't have right to access the HTTP server (e.g. failed in HTTP authorization ).
So in this case the client should look at the response body to see if it is a business logic error or solely a server error.
For a 404 the client don't know if the resources on the server doesn't exist, or the business object doesn't exist. It has to look into the response body also.
So why would people keep using HTTP response code with business logic error? To me it is more simple to simply look into the response body for a business logic error and handle it. Is there any situation that using HTTP response with a business logic error is necessary?
Many thanks.
So why would people keep using HTTP response code with business logic error?
When creating applications that follow the REST architetural style over the HTTP protocol, you adapt your application domain to resources, which is the central piece of the REST architecture.
The server provide a set of URLs to locate the resources and their state can be manipulated via HTTP verbs and representations such as JSON and/or XML. And HTTP status codes are used to inform the client regarding the status of the operation. A misleading status code will convey wrong information about the status of the request.
The RFC 7231 defines classes of status codes:
1xx (Informational): The request was received, continuing process
2xx (Successful): The request was successfully received, understood, and accepted
3xx (Redirection): Further action needs to be taken in order to complete the request
4xx (Client Error): The request contains bad syntax or cannot be fulfilled
5xx (Server Error): The server failed to fulfill an apparently valid request
For example, if the request has failed due to a client error (for instance, malformed request or invalid data has been provided in the payload), returning a 2xx or 5xx status code is misleading here. A 4xx status code would be suitable to express what caused the error.
Is there any situation that using HTTP response with a business logic error is necessary?
Some status such as 409 and 422 may be used to represent business logic errors.
To me it is more simple to simply look into the response body for a business logic error and handle it.
It's true that HTTP status codes are sometimes not sufficient to convey enough information about an error to be helpful. But the RFC 7807 was created to fill this gap: it defines simple JSON and XML documents to indicate problems.
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.
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.