Status codes

Requests requiring no action

If a request attempts to put a resource into a state which it is already in, the status code SHOULD be in the 2xx range. In other words, the status code SHOULD match what would be given if a change had been required.

This may not always be practical, however. If a client makes a DELETE request for a resource that has already been deleted, the server is not required to maintain a record of the deleted resource and MAY respond with 404. ^[3]

URI ambiguity

URI ambiguity requiring the use of a 300 status code SHOULD be avoided by following the below principles:

1. URI schemes SHOULD be inherently unambiguous with respect to what resource is meant.
2. If multiple representations of a particular resource are offered, the desired version SHOULD be specified with an Accept header rather than distinct URIs, and a default representation SHOULD be served liberally.^[5]

However, in such cases where it is deemed important that an occasionally-ambiguous URI scheme be used or where different representations of a resource require differing URIs (e.g., for media files where a file extension is considered significant), a 300 status code MAY be returned where a particular URI is ambiguous.

301, 302, 303, and 307 response bodies

To facilitate programmatic use, a response body SHOULD accompany any 301, 302, 303, or 307 response. If a response body is provided, it MUST have the same Content-Type as a 2xx response to the same request would have, and MUST contain the following fields:

For example, clients using a content type of application/json might receive:

{
   "code": "remote_region",
   "message": "The requested resource is in a different region",
   "target": {
     "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:r134-a0c07083-f411-446c-9316-7b08d6448c86",
     "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86",
     "id": "r134-a0c07083-f411-446c-9316-7b08d6448c86",
     "name": "my-share",
     "remote": {
        "region": {
           "href": "https://us-east.iaas.cloud.ibm.com/v1/regions/us-south",
           "name": "us-south",
	   "resource_type": "region"
         }
      },
      "resource_type": "share"
   }
}

If a client makes a request that includes mismatched identifiers (for example, child and parent identifiers that both exist, but do not have a relationship), the request MUST fail with 404 rather than be redirected.

303 and 307 temporary redirects

A 303 in response to a POST, PUT, or DELETE indicates that the operation has succeeded but that the response entity-body is not being sent along with this request. If the client wants the response entity-body, it needs to make a GET request to the URI provided in the Location header.

A 307 in response to a POST, PUT, or DELETE indicates that the server has not even tried to perform the operation and the client needs to resubmit the entire request, with the original method, to the URI in the Location header.

Security implications of 401 and 403

There may be times when returning a 401 or a 403 would reveal the presence of a resource on the server that a client should not be allowed to know exists. In these cases, the server MUST respond with the status code that would be used if the resource did not exist, even for requests that would succeed with proper authentication.

For example, for a GET request for a resource that the client is not allowed to know exists, the server MUST respond with a 404 Not Found. Or, for the creation of a binding to that resource, the server MUST respond with a 400 Bad Request, exactly as if the resource did not exist.

Conflicts

Though RFC 7231 suggests 409 Conflict be limited to conflicts between a request and the "target resource," this handbook recommends a broader view of what constitutes a conflict. Specifically, a request SHOULD be deemed in conflict (and receive a 409 status code) if the request is syntactically and semantically valid but cannot be processed because of the client-mutable state of one or more existing resources that would be used by the request in a way the system deems invalid.

409 Conflict SHOULD NOT be returned for a request that the system can determine could not be successfully resubmitted after the client made other requests to resolve conflicts with the state of existing resources.

The following scenarios SHOULD result in a 409 Conflict:

• A request would update a certain property in a resource with a value that isn't compatible with the current value of another property in the resource.
• A request would update or create a resource with a binding to an existing resource that already has an exclusive binding or has reached its binding limit.
• A request would use an existing resource (for example, to generate a new resource) which has client-mutable state preventing such use.
• A request would delete a resource that another resource depends on.

The following scenarios MUST NOT result in a 409 Conflict:

• A request has an internal conflict. This SHOULD result in a 400 Bad Request.
• A request depends on a resource that does not exist. This SHOULD result in a 400 Bad Request.
• A request would update or create a resource with a binding to an existing resource that the user is unauthorized to bind to. This SHOULD result in a 403 Forbidden unless the user is not permitted to know about the existing resource.
• A request would conflict with state that is invisible to clients. This MUST NOT happen by design, but unexpected runtime scenarios MAY result in a 500 Internal Server Error.
• A request would conflict with state that is immutable for clients. This SHOULD result in a 400 Bad Request.
• A safe^[11] request cannot be made because of the current state of the system. This SHOULD NOT happen by design. Consider modeling the missing functionality as an "empty" resource with a 200 OK response or an absent resource with a 404 Not Found response.

The following scenarios SHOULD NOT result in a 409 Conflict:

• A request cannot be processed because of transient resource state and the client is advised to wait for that state to change and retry the request. This SHOULD NOT happen by design, but if it does, it MAY result in a 409 Conflict.
• A request would update or create a resource with a binding to an existing resource which has irrecoverably failed or expired. This SHOULD result in a 400 Bad Request.
• A request would use an existing resource (for example, to generate a new resource) which has irrecoverably failed or expired. This SHOULD result in a 400 Bad Request.

500 and 503 errors

Because the client can do nothing to fix a 500 or 503 status code (and can only try again later), it MUST be considered a critical application failure whenever one of those status codes is returned in production. For more information on this and error response models, see the handbook's documentation on Errors.