Error & Status Codes

[kinlane]

Need to come up with the standard for returning error and status codes -- there is no plan so far. I'd like to see this span a standard error responses structure, as well as application of HTTP status codes.

HTTP Status Success

• 200 OK - Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.
• 201 Created - The request has been fulfilled, resulting in the creation of a new resource.
• 202 Accepted - The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs.
• 204 No Content - The server successfully processed the request and is not returning any content.
• 206 Partial Content - The server is delivering only part of the resource (byte serving) due to a range header sent by the client. The range header is used by HTTP clients to enable resuming of interrupted downloads, or split a download into multiple simultaneous streams.

HTTP Status Redirection

• 301 Moved Permanently - This and all future requests should be directed to the given URI.
• 302 Found - 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.
• 303 See Other - The response to the request can be found under another URI using a GET method. When received in response to a POST (or PUT/DELETE), the client should presume that the server has received the data and should issue a redirect with a separate GET message.
• 304 Not Modified - Indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match. In such case, there is no need to retransmit the resource since the client still has a previously-downloaded copy.

HTTP Status User Error

• 400 Bad Request - The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, too large size, invalid request message framing, or deceptive request routing).
• 401 Unauthorized - Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
• 403 Forbidden - The request was a valid request, but the server is refusing to respond to it. The user might be logged in but does not have the necessary permissions for the resource.
• 404 Not Found - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
• 405 Method Not Allowed - A request method is not supported for the requested resource; for example, a GET request on a form which requires data to be presented via POST, or a PUT request on a read-only resource.
• 406 Not Acceptable - The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.
• 408 Request Timeout - The server timed out waiting for the request. According to HTTP specifications: The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time.
• 409 Conflict - Indicates that the request could not be processed because of conflict in the request, such as an edit conflict between multiple simultaneous updates.
• 410 Gone - Indicates that the resource requested is no longer available and will not be available again. This should be used when a resource has been intentionally removed and the resource should be purged. Upon receiving a 410 status code, the client should not request the resource in the future. Clients such as search engines should remove the resource from their indices. Most use cases do not require clients and search engines to purge the resource, and a 404 Not Found may be used instead.
• 411 Length Required - The request did not specify the length of its content, which is required by the requested resource.
• 412 Precondition Failed - The server does not meet one of the preconditions that the requester put on the request.
• 415 Unsupported Media Type - The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.
• 422 Unprocessable Entity - The request was well-formed but was unable to be followed due to semantic errors.
• 423 Locked - The resource that is being accessed is locked.
• 428 Precondition Required - The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.
• 429 Too Many Requests - The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.

HTTP Status Server Error

• 500 Internal Server Error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
• 501 Not Implemented - The server either does not recognize the request method, or it lacks the ability to fulfill the request. Usually this implies future availability (e.g., a new feature of a web-service API).
• 503 Service Unavailable - The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.

[switzersc]

@kinlane what are the next steps you're thinking for this? When you say "application of HTTP status codes" ,do you mean implementation in the API layer or documentation in the spec, or something else? Just looking to see if/how I can contribute here.

[kinlane]

My goal is to have the OpenAPI provide guidance for practitioners beyond just basic 200, 404, and 500. Providing real examples of mature responses. So to answer you, I guess d) all the above. I wrote this as I was designing and deploying the demo. Which I was starting to make reflect in the OpenAPI for the spec, which will translate into the documentation that gets generated.

At first I'm just looking to suggest a handful of core reponse codes, with basic guidance in spec, but links to educate implementers about proper usage -- we'll see where goes from there.

[kinlane]

I'm suggesting that for v1.1 we only provide guidance on successful 200 response providing HSDS compliant JSON.

In v1.2 I will provide more guidance on further HTTP status code recommendations and possibly common schema for errors.

[NeilMcKLogic]

I like the implementation of a reasonable number of these error codes. It is more informative to human users (we devs) and also lets us more programatically respond to different error scenarios beyond a simple binary choice of "it succeeded" and "it failed".

[kinlane]

@NeilMcKechnie precisely. As a developer, I really appreciate having this stuff well defined so when I have my blinders on I can just implement. The HTTP status code vocabulary is robust, and it just makes sense for us to provide guidance for developers to help them ensure their implementations are as communicative as possible.