REST API Status Codes
HTTP defines these standard status codes that can be used to convey the results of a client’s request. The status codes are divided into the five categories.
- 1xx: Informational : Communicates transfer protocol-level information.
- 2xx: Success: Indicates that the client’s request was accepted successfully.
- 3xx: Redirection: Indicates that the client must take some additional action in order to complete their request.
- 4xx: Client Error : This category of error status codes points the finger at clients.
- 5xx: Server Error : The server takes responsibility for these error status codes.
100 Continue
An interim response. Indicates the client that the initial part of the request has been received and has not yet been rejected by the server. The client SHOULD continue by sending the remainder of the request or, if the request has already been completed, ignore this response. The server MUST send a final response after the request has been completed.
101 Switching Protocol
Sent in response to an Upgrade request header from the client, and indicates the protocol the server is switching to.
102 Processing (WebDAV)
Indicates that the server has received and is processing the request, but no response is available yet.
103 Early Hints
Primarily intended to be used with the Link header. It suggests the user agent start preloading the resources while the server prepares a final response.
200 OK
Request accepted, response contains result. This is a general purpose response code that can be returned from any request. For GET requests, the requested resource or data is in the response body. For PUT or DELETE requests, the request was successful and information about the result (such as new resource identifiers, or changes in resource status) can be found in the response body.
Unlike the 204 status code, a 200 response should include a response body. The information returned with the response is dependent on the method used in the request, for example:
- GET an entity corresponding to the requested resource is sent in the response.
- HEAD the entity-header fields corresponding to the requested resource are sent in the response without any message-body.
- POST an entity describing or containing the result of the action.
- TRACE an entity containing the request message as received by the end server.
201 CREATED
This response code is returned from PUT or POST, and indicates that a new resource was created successfully. The response body might for example contain information about a new resource, or validation information (for example, when an asset is updated).
The origin server MUST create the resource before returning the 201 status code. If the action cannot be carried out immediately, the server SHOULD respond with a 202 (Accepted) response instead.
202 Accepted
A 202 response is typically used for actions that take a long while to process. It indicates that the request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, or even maybe disallowed when processing occurs.
Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent’s connection to the server persist until the process is completed.
The entity returned with this response SHOULD include an indication of the request’s current status and either a pointer to a status monitor (job queue location) or some estimate of when the user can expect the request to be fulfilled.
204 NO CONTENT
Indicates that the request was accepted but that there was nothing to return. This is returned when the request was processed, but no additional information about the result has been returned.
The 204 status code is usually sent out in response to a PUT, POST or DELETE request when the REST API declines to send back any status message or representation in the response message’s body.
302 Found
The HTTP response status code 302 Found is a common way of performing URL redirection. An HTTP response with this status code will additionally provide a URL in the Location header field. The user agent (e.g., a web browser) is invited by a response with this code to make a second. Otherwise identical, request to the new URL specified in the location field.
Many web browsers implemented this code in a manner that violated this standard, changing the request type of the new request to GET, regardless of the type employed in the original request (e.g., POST). RFC 1945 and RFC 2068 specify that the client is not allowed to change the method on the redirected request. The status codes 303 and 307 have been added for servers that wish to make unambiguously clear which kind of reaction is expected of the client.
304 Not Modified
This status code is similar to 204 (“No Content”) in that the response body must be empty. The critical distinction is that 204 is used when there is nothing to send in the body, whereas 304 is used when the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match.
In such a case, there is no need to retransmit the resource since the client still has a previously-downloaded copy.
Using this saves bandwidth and reprocessing on both the server and client, as only the header data must be sent and received in comparison to the entirety of the page being re-processed by the server, then sent again using more bandwidth of the server and client.
400 BAD REQUEST
The request was not valid. This code is returned when the server has attempted to process the request, but some aspect of the request is not valid, for example an incorrectly formatted resource or an attempt to deploy an invalid event project to the event runtime. Information about the request is provided in the response body, and includes an error code and error message. The client SHOULD NOT repeat the request without modifications.
401 UNAUTHORIZED
Is returned from the application server when application security is enabled, and authorization information was missing from the request.A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. It may have provided the wrong credentials or none at all. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
The client MAY repeat the request with a suitable Authorization header field. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. 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 SHOULD be presented the entity that was given in the response, since that entity might include relevant diagnostic information.
403 FORBIDDEN
Indicates that the client attempted to access a resource which they do not have access to. This might be encountered if the user accessing the remote resource does not have sufficient privileges; for example, by having the WBERestApiUsers or WBERestApiPrivilegedUsers role. Users who attempt to access private event projects owned by other users might also see this error, but only if they have the WBERestApiUsers role rather than the WBERestApiPrivilegedUsers role.
404 NOT FOUND
Indicates that the targeted resource does not exist. This might be because the URI is malformed, or the resource has been deleted.
405 METHOD NOT ALLOWED
Returned when the targeted resource does not support the requested HTTP method; for example, the functions resource only allows GET operations.
406 NOT ACCEPTABLE
The data format requested in the Accept header or accept parameter is not supported by the targeted resource. That is, the client has requested that data is returned in a particular format, but the server is unable to return data in that format.
409 CONFLICT
Indicates that a conflicting change has been detected during an attempt to modify a resource. The response body provides further information.
412 Precondition Failed
The 412 (Precondition Failed) status code indicates that one or more conditions given in the request header fields evaluated to false when tested on the server. This response code allows the client to place preconditions on the current resource state (its current representations and metadata) and, thus, prevent the request method from being applied if the target resource is in an unexpected state.
415 UNSUPPORTED MEDIA TYPE
The data format of the request body, specified in the Content-Type header, is unsupported by the targeted resource.
417 Expectation Failed
The 417 (Expectation Failed) status code indicates that the expectation given in the request’s Expect header field could not be met by at least one of the inbound servers.
Expect
The "Expect" header field in a request indicates a certain set of
behaviors (expectations) that need to be supported by the server in
order to properly handle this request. The only such expectation
defined by this specification is 100-continue.
Expect = "100-continue"
The Expect field-value is case-insensitive.
A server that receives an Expect field-value other than 100-continue
MAY respond with a 417 (Expectation Failed) status code to indicate
that the unexpected expectation cannot be met.
A 100-continue expectation informs recipients that the client is
about to send a (presumably large) message body in this request and
wishes to receive a 100 (Continue) interim response if the
request-line and header fields are not sufficient to cause an
immediate success, redirect, or error response. This allows the
client to wait for an indication that it is worthwhile to send the
message body before actually doing so, which can improve efficiency
when the message body is huge or when the client anticipates that an
error is likely (e.g., when sending a state-changing method, for the
first time, without previously verified authentication credentials).
For example, a request that begins with
PUT /somewhere/fun HTTP/1.1
Host: origin.example.com
Content-Type: video/h264
Content-Length: 1234567890987
Expect: 100-continue
allows the origin server to immediately respond with an error
message, such as 401 (Unauthorized) or 405 (Method Not Allowed),
before the client starts filling the pipes with an unnecessary data
transfer.
Requirements for clients:
- A client MUST NOT generate a 100-continue expectation in a request
that does not include a message body.
- A client that will wait for a 100 (Continue) response before sending the request message body MUST send an Expect header field
containing a 100-continue expectation.500 INTERNAL SERVER ERROR
An internal error occurred in the server. This might indicate a problem with the request, or might indicate a problem in the server side code. Error information can be found in the response body.
501 Not Implemented
The server either does not recognize the request method, or it cannot fulfill the request. Usually, this implies future availability (e.g., a new feature of a web-service API).
