The API aims to follow REST standards, and hopefully with time become a true REST API. In order to conform with REST standards, we use HTTP RESPONSE CODES to give an indication of what is going on in the API. This documentation will give a quick runthrough of the different return values, and when used.
The base for this is gathered from here.
Resources:
The HTTP 100 Continue informational status response code indicates that everything so far is OK and that the client should continue with the reqeust or ignore it if it is already finished.
To have a server check the request’s headers, a client must send Except : 100-continue as a header in its initial request and receive a 100 Continue status code in response before sending the body.
The HTTP 101 Switching Protocols response code indicates a protocol to which the server switches. The protocol is specified in the Upgrade request header received from a client.
The server includes in this response an Upgrade response hader to indicate the protocol it switched to. The process is described in the following article: Protocol upgrade mechanism.
UpgradeThe HTTP 103 Early Hints information response status code is primarily intended to be used with the Link header to allow the user agent to start preloading resources while the server is still preparing a response.
Link[!WARNING] No compatibility data found for
http.status.103.Check for problems with this page or contribute missing data to mdn/browser-compat-data.
The HTTP 200 OK success status response code indicates that the request has succeeded. A 200 response is cahcable by default.
The meaning of a success depends on the HTTP request method:
GET: The resource has been fetched and is transmitted in the message body.HEAD: The representation headers are included in the response without any message body.POST: The resource describing the result of the action is transmitted in the message body.TRACE: The message body contains the request message as received by the server.The successresult of a PUT or a DELETE is often not a 200 OK but a 204 No Content (or a 201 Created whenthe resource is uploaded for the first time).
The HTTP 201 Create success status response code indicates that the request has succeeded and has lead to the creation of a resource. The new resource is effectively created before this response is sent back and the new resource is returned in the body of the message, its location being either the URL of the request, or the content of the Location header.
In the API this generally means that a database item have been created.
The HTTP 202 Accepted response status code indicates that the request has been accepted for processing, but the processing has not been completed; in fact, processing may not have started yet. The request might or might not eventually be acted upo, as it might be disallowed when processing actually takes place.
202 is non-committal, meaning that there is no way for the HTTP to later send an asynchronous response indicating the outcome of processing the request. It is intended for cases where another process or server handles the request, or for batch processing.
The API uses this response when content have been altered.
AcceptThe HTTP 203 Non-Authoritative Information response status indicates that the request was successful but the enclosed payload has been modified by a transforming proxy from that of the origin server’s 200 OK response.
The 203 response is similar to the value 214, meaning Transformation Applied, of the Warning header code, which has the additional adventage of being applicable to responses with any status code.
WarningThe HTTP 204 No Content success status response code indicates that a request has succeeded, but that the client doesn’t need to navigate away from its page.
This might be used, for example, when implementing "save and continue editing" functionality for a wiki site. In this case a PUT request would be used to save the page, and the 204 No Content response would be sent to indicate that the editor should not be replaced by some other page.
A 204 response is cachable by default (an ETag header is included in such a response).
The HTTP 205 Reset Content response status tells the client to reset the document view, so for example to clear the content of a form, reset a canvas state, or to refresh the UI.
204 No Content for more detail.The HTTP 206 Partial Content success status response code indicates that the request has succeeded and the body contains the requested range of data, as described in the Range header of the request.
If there is only one range, teh Content-Type of the whole response is set to the type of the document, and a Content-Range is provided.
If several ranges are sent back, the Content-Type is set to multipart/byteranges and each fragment covers one range, with Content-Range and Content-Type describing it.
The HTTP 300 Multiple Choices redirect status response code indicates that the request has more than one possible responses. The user-agent or the user should choose one of them. As there is no standardized way to choosing one of the responses, this response code is very rarely used.
If the server has a preferred choice, it should generate a Location header.
The HTTP 301 Moved Permanently redirect status response code indicates that the requested resource has been definitively moved to the URL given by the Location headers. A browser redirects to the new URL and search engines update their links to the resource.
The HTTP 302 Found redirect status response code indicates that the resource requested has been temporarily moved to the URL given by the Location header. A browser redirects to this page but search engines don’t update their links to the resource (in ‘SEO-speak’, it is said that the ‘link-juice’ is not sent to the new URL).
Even if the specification requires the method (and the body) not to be altered when the redirection is performed, not all user-agents conform here - you can still find this type of bugged software out there. It is therefore recommended to set the 302 code only as a response for GET or HEAD methods and to use 307 Temporary Redirect instead, as the method change is explicitly prohibited in that case.
In the case where you want the method used to be changed to GET, use 303 See Other instead. This is useful when you want to give a response to a PUT method that is not the uploaded resource but a confirmation message such as: ‘you successfully uploaded XYZ’.
The HTTP 303 See Other redirect status response code indicates that the redirects don’t link to the requested resource itself, but to another page (such as a confirmation page, a representation of a real-world object - see HTTP range-14 - or an upload-progress page). This response code is often sent back as a result of PUT or POST. The method used to display this redirected page is always GET.
The HTTP 304 Not Modified clien redirection response code indicates that there is no need to retransmit the requested resources. It is an implicit redirection to a chached resource. This happens when the request method is a safe method, such as GET or HEAD, or when the request is conditional and uses an If-None-Match or an If-Modified-Since header.
The equivalent 200 OK response would have included the headers Cache-Control, Content-Location, Date, ETag, Expires, and Vary.
The HTTP 307 Temporary Redirect redirect status response code indicates that the resource requested has been temporarily moved to the URL given by the Location headers.
The method and the body of the original request are reused to perform the redirected request. In the cases where you want the method used to be changed to GET, use 303 See Other instead. This is useful when you want to give an answer to a PUT method that is not the uploaded resources, but a confirmation message (like “You successfully uploaded XYZ”).
The only difference between 307 and 302 is that 307 guarantees that the method and the body will not be changed when the redirected request is made. With 302, some old clients were incorrectly changing the method to GET: the behavior with non-GET methods and 302 is then unpredictable on the Web, whereas the behavior with 307 is predictable. For GET requests, their behavior is identical.
The HTTP 308 Permanent Redirct redirect status response code indicates that the resource requested has been definitively moved to the URL given by the Location headers. A browser redirects to this page and search engines update their links to the resource (in ‘SEO-speak’, it is said that the ‘link-juice’ is sent to the new URL).
The request method and the body will not be altered, whereas 301 may incorrectly sometimes be changed to a GET method.
[!NOTE]
Note: Some Web Applications may use the
308 Permanent Redirectin a non/standard way for other purposes. For example, Google Drive uses a308 Resume Incompleteresponse to indicate to the client when an inclomplete upload stalled. (See Perform a resumable download on Google Drive documentation.)
The HTTP 400 Bad Request response status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error.
The API serves this when mandatory fields are missing, fields are out of range, or other similar conditions.
The HTTP 401 Unauthorized response status code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.
The API serves this when authorization conditions are not met. Check that you are using the right credentials for your request, or for certain layers that you access with a HTTPS request.
The HTTP 402 Payment Required is a nonstandard response status code that is reserved for future use. This status code was created to enable digital cash or (micro) payment systems and would indicate that the requested content is not available until the client makes a payment.
Sometimes, this status code indicates that the request cannot be processed until the client makes a payment. However, no standard use convention exists and different entities use it in different contexts.
The HTTP 403 Forbidden response status code indicates that the server understands the request but refuses to authorize it.
This status is returned by the web service, and not the API, meaning you are trying to access server resources that are forbidden.
The HTTP 404 Not Found response status code indicates that the server cannot find the requested resource. Links that lead to a 404 page are often called broken or dead and can be subject to link rot.
This status is returned by the web service, and not the API, meaning you are trying to access server resources that doesn’t exist.
If a link to a API resource results in this status code, check that you are calling the correct resource name. Check also API documentation against the latest version, as resources might be moved around the server.
The HTTP 405 Method Not Allowed response status code indicates that the server knows the request method, but the target resource doesn’t support this method.
The server must generate an Allow header field in a 405 status code response. The field must contain a list of methods that the target resource currently supports.
AllowThe HTTP 406 Not Acceptable client error response code indicates that the server cannot produce a response matching the list of acceptable values defined in the request’s proactive content negotiation headers, and that the server is unwilling to supply a default presentation.
Proactive content negotiation headers include:
AcceptAccept-EncodingAccept-LanguageIn practice, this error is very rarely used. Instead of responding using this error code, which would be cryptic for the end user and difficult to fix, servers ignore the relevant header and serve an actual page to the user. It is assumed that even if the user won’t be completely happy, they will prefer this to an error code.
If a server returns such an error status, the body of the message should contain the list of the available representaions of the resources, allowing the user to choose among them.
The HTTP 407 Proxy Authentication Required client error status response code indicates that the request has not been applied because it lacks valdi authentication credentials for a proxy server that is between the browser and the server that can access the requested resource.
This status is sent with a Proxy-Authenticate header that contains information on how to authorize correctly.
The HTTP 408 Request Timeout response status code means that the server would like to shut down this unused connection. It is sent on an idle connection by some servers, even without any previous request by the client.
A server should send the “close” Connection header field in the response, since 408 implies that the server has decided to close the connection rather than continue waiting.
This response is used much more since some browsers, like Chrome, Firefox 27+, and IE9, use HTTP pre-connection mechanisms to speed up surfing.
[!NOTE] Note: some serveres merely shut down the connection without sending this message.
ConnectionX-DNS-Prefetch-ControlThe HTTP 409 Conflict response status code indicates a request conflict with the current state of the target resource.
Conflicts are most likely to occur in response to a PUT request. For example you may get a 409 response when uploading a file that is older than the existing one on the server, resulting in a version control conflict.
The HTTP 410 Gone client error response code indicates that access to the target resource is no longer available at the origin server and that this condition is likely to be permanent.
If you don’t know wherther this condition is temporary or permanent, a 404 status code should be used instead.
[!NOTE] Note: A 410 response is chacheable by default.
The HTTP 411 Length Required client error response code indicates that the server refuses to accept the request without a defined Content-Length header.
[!NOTE] Note: by specification, when sending data in a series of chunks, the
Content-Lengthheader is omitted and at the beginning of each chunk you need to add the length of the current chunk in hexadecimal format. See Transfer-Encoding for more details.
The HTTP 412 Precondition Failed cloent error response code indicates that access to the target resource has been denied. This happens with conditional requests or methods other than GET or HEAD when the condition defined by the If-Unmodified-Since or If-None-Match headers is not fulfilled. In that case, the request, usually an upload or a modification of a resource, cannot be made and this error response is sent back.
The HTTP 413 Payload Too Large response status code indicates that the request entity is larger than limits defined by server; the server might close the connection or return a Retry-After header field.
ConnectionRetry-AfterThe HTTP 414 URI Too Long response status code indicates that the URI requested by the client is longer than the server is willing to interpret.
There are a few rare conditions when this might occur:
POST request to a GET request with long query information,See also
The HTTP 415 Unsupported Media Type client error response code indicates that the server refuses to accept the request because the payload format is in an unsupported format.
The format problem might be due to the request’s indicated Content-Type or Content-Encoding, or as a result of inspecting the data directly.
The HTTP 416 Range Not Satisfiable error response code indicates that a server cannot serve the requested ranges. The most likely reason is that the document doesn’t contain such ranges, or that the Range header value, though syntactically correct, doesn’t make sense.
The 416 response message contains a Content-Range indicating an unsatisfied range (that is a '*') followed by a '/' and the current length of the resource. E.g. Content-Range: bytes */1277
Faced with this error, browsers usually either abort the operation (for example, a download will be considered as non-resumable) or ask for the whole document again.
The HTTP 417 Expectation Failed client error response code indicated that the expectation given in the request’s Expect header could not be met.
See the Expect header for more details.
The HTTP 418 I'm a teapot client error response code indicates that the server refuses to brew coffee because it is, permanently, a teapot. A combined coffee/tea pot that is temporarily out of coffee should instead return 503. This error is s reference to Hyper Text Coffee Pot Control Protocol defined in April Fool’s jokes in 1998 and 2014.
Some websites use this response for request they do not wish to handle, such as automated queries.
The HTTP 422 Unprocessable Entity response status code indicates that the server undestands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
[!WARNING] Warning: The client should not repeat this request without modification.
[!CAUTION] Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The HTTP 425 Too Early response status code indicates that the server is unwilling to risk processing a request that might be replayed, which creates the potential for a reply attack.
The HTTP 426 Upgrade Requierd client error response code indicates that the server refuses to perform the request using the current protocol but might be willing to do so after the client upgrades to a different protocol.
The server sends an Upgrade header with this response to indicate the required protocol(s).
The HTTP 428 Precindition Required response status code indicates that the server requires the request to be conditional.
Typically, this means that a required precondiotn header, such as If-Match, is missing.
When a precondition header is not matching the server side state, the response should be 412 Precondition Failed.
The HTTP 429 Too Many Requests response status code indicates the user has sent too many requests in a given amount of time (“rate limiting”).
A Retry-After header might be included to this response indicating how long to wait before making a new request.
Retry-AfterThe HTTP 431 Request Header Fields Too Large response status code indicates that the server refuses to process the request because the request’s HTTP headers are too long. The request may be resubmitted after reducing the size of the request headers.
431 can be used when the total size of request headers is too large, or when a single header field is too large. To help those running into this error, indicate which of the two is the problem in the response body - ideally, also include which headers are too large. This lets users attempt to fix the problem, such as by clearing their cookies.
Servers will often prduce this status if:
Referer URL is too longCookies sent in the requestSee Also
The HTTP 451 Unavailable For Legal Reasons client error response code indicates that the user requested a resource that is not available due to legal reasons, such as a web page for which a legal action has been issued.
[!NOTE] Note: the
Linkheader might also contain arel="blocked-by"relation identifying the entity and implementing blockage, not any other entity mandating it.
Any attempt to identify the entity ultimately responsible for the resource being unavailable belongs in the response body, not the rel="blocked-by" link. This includes the name of the perrson or organization that made a legal demand resulting in the content’s removal.
This example response is taken from the IETF RFC and contains a reference to Monty Python’s Life of Brian
HTTP/1.1 451 Unavailable For Legal Reasons
Link: <https://spqr.example.org/legislatione>; rel="blocked-by"
Content-Type: text/html
<html>
<head><title>Unavailable For Legal Reasons</title></head>
<body>
<h1>Unavailable For Legal Reasons</h1>
<p>This request may not be serviced in the Roman Province
of Judea due to the Lex Julia Majestatis, which disallows
access to resources hosted on servers deemed to be
operated by the People's Front of Judea.</p>
</body>
</html>The HTTP 500 Internal Server Error server error response code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request
This error response is a generic "catch-all" response. Usually, this indicates the server cennot find a better 5xx error code to response. Sometimes, server administrators log error responses like 500 status code with more details about the request to prevent the error from happening again in the future.
This error can occure on the test server during coding, as code are developed live. Usually this means a programming error within the code, and will be corrected as quick as possible. The developer is usually aware of this situation in such occasions.
The HTTP 501 Not Implemented server error response code means that the server dos not support the functionality required to fulfill the request.
This status can also send a Retry-After header, telling the requester when to check back to see if the functionality is supported by then.
501 is the appropriate response when the server does nto recognize the request method and is incapable of supporting it for any resource. The only methods that servers are required to suport (and therefor that must not return 501) are GET and HEAD.
If the server does recognize the method, but intentionally does not support it, the appropriate response is 405 Method Not Allowed.
[!NOTE]
- A
501error is not something you can fix, but requires a fix by the web server you are trying to access.- A
501response is cacheable by default; that is, unless caching headers instruct otherwise.
The HTTP 502 Bad Gateway server error response code indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server.
[!NOTE] Note: A Gateway might refer to different things in networking and a
502error is usually not something you can fix, but requires a fix by the web server or the proxies you are trying to get access through.
The HTTP 503 Service Unavaiilable server error response code indicates that the server is not ready to handle the request.
Common causes are a server that is down for maintenance or that is overloaded. This response should be used for temporary conditions and the Retry-After HTTP header should, if possible, contain the estimated time for the recovery of the service.
[!NOTE] Note: together with this response, a user-friendly page explaining the problem should be sent.
Caching-related headers that are sent along with this response should be taken care of, as a 503 status is often a temporary condition and responses shouldn’t usually be cached.
Retry-AfterThe HTTP 504 Gateway Timeout server error response code indicates that the server, while acting as a gateway or procy, did not get a response in time from the upstream server that it needed in order to complete the request.
[!NOTE] Note: A Gateway might refer to different things in networking and a
504error is usually not something you can fix, but requires a fix by the web server or the proxies you are trying to get access through.
The HTTP 505 HTTP Version Not Supported response status code indicates that the HTTP version used in the request is not supported by the server.
UpgradeThe HTTP 506 Variant Also Negotiates response status code may be given in the context of Transparent Content Negotiation (see RFC 2295). This protocol enables a client to retrieve the best variant of a given resource, where the server supports multiple variants.
The Variant Also Negotiates status code indicates an internal server configuration error in which the chosen variant is itself configured to engage in content negotiation, so is not proper negotiation endpoint.
The HTTP 507 Insufficient Storage response status code may be given in the context of the Web Distributed Authoring and Versioning (WebDAV) protocol (see RFC 4918).
It indicates that a method could not be performed because the server cannot store the representation needed to successfully complete the request.
The HTTP 508 Loop Detected response status code may be given in the context of the Web Distributed Authoring and Versioning (WebDAV) protocol.
It indicates that the server terminated an operation because it encountered an infinite loop while processing a request with “Depth: infinity”. This status indicates that the entire operation failed.
The HTTP 510 Not Extended response status code is sent in the context of the HTTP Extension Framework, defined in RFC 2774.
In that specification a client may send a request that contains an extension declaration, that describes the extension to be used. If the server receives such a request, but any described extensions are not supported for the request, then the server respons with the 510 status code.
The HTTP 511 Network Authentication Required response status code indicates that the client needs to authenticate to gain network access.
This status is not generated by origin server, but by intercepting proxies that control access to the network.
Network operators sometimes require some authentication, acceptance of terms, or other user interaction before granting access (for example in an internet café or at an airport). They often identify clients who have not done so using their Media Access Control (MAC) addresses.