[ADP-200] HTTP Status

reviewing phase 1

Re-check documentation necessary.
Add related ADPs.

HTTP status codes are standardized codes that indicate the result of an HTTP request. These codes are divided into five categories:

1xx (Informational): The request was received, and the process is continuing.
2xx (Success): 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 a valid request.

HTTP Status Codes Usage

Code	Description	Usage	Documentation
Success Codes
200	OK	use	document all
201	Created	use	document POST, PUT
202	Accepted	use	document POST, PUT, PATCH, DELETE
204	No Content	use	document POST, PUT, PATCH, DELETE
205	Reset Content	do not use	all
206	Partial Content	not use for pagination	all
207	Multi-Status	use	document POST (DELETE)
Redirection Codes
301	Moved Permanently	do not use	all
302	Found	do not use	all
303	See Other	do not use	POST, PUT, PATCH, DELETE
304	Not Modified	document	GET, HEAD
307	Temporary Redirect	do not use	all
308	Permanent Redirect	do not use	all
Client Side Error Codes
400	Bad Request	use	document all
401	Unauthorized	use	do not document all
403	Forbidden	do not document	all
404	Not Found	use	do not document all
405	Method Not Allowed	document	all
406	Not Acceptable	use	do not document all
407	Proxy Authentication Required	do not use	all
408	Request Timeout	do not use	all
409	Conflict	document	POST, PUT, PATCH, DELETE
410	Gone	do not document	all
411	Length Required	document	POST, PUT, PATCH
412	Precondition Failed	use	do not document PUT, PATCH, DELETE
413	Payload Too Large	use	all
415	Unsupported Media Type	use	do not document POST, PUT, PATCH
417	Expectation Failed	do not use	all
418	I’m a Teapot	do not use	all
422	Unprocessable Content	do not use	all
423	Locked	document	PUT, PATCH, DELETE
424	Failed Dependency	do not use	all
428	Precondition Required	use	do not document all
429	Too Many Requests	use	do not document all
431	Request Header Fields Too Large	do not document	all
Server Side Error Codes
500	Internal Server Error	use	do not document all
501	Not Implemented	document	all
502	Bad Gateway		is meaningless
503	Service Unavailable	use	do not document all
504	Gateway Timeout	use	all
505	HTTP Version Not Supported	do not use	all
507	Insufficient Storage	do not document	POST, PUT, PATCH
511	Network Authentication Required	do not use	all

Legend:

use: A common, well-understood status code that should be used where appropriate. This does NOT mean that every operation must return this code.
do not use: The status code is not seen as beneficial for returning from a RESTful API. It might be applicable in other contexts, such as being returned by reverse proxies or for web pages.
document: If the status code can be returned by the API, it should be documented in the API specification.
do not document: The status code has a well-understood standard meaning, so it should only be documented if there are operation-specific details to add.

HTTP Status Codes - Usage Guidelines

Code	Description	When to Use	Reason for Do Not Use (if applicable)
Success Codes
200	OK	Standard success response. Use when the request was successful and there is a response body.
201	Created	Use when a resource has been successfully created. Return the created resource or set the Location header with the URI of the new resource.
202	Accepted	Use when the request has been accepted for processing, but the processing is not complete. Applicable for asynchronous operations.
204	No Content	Use when the request was successful, but there is no response body (e.g., successful DELETE or PUT request).
205	Reset Content		Meant for interactive use cases like clearing a form. No reason to use it in a REST API.
206	Partial Content		For responses to range requests when only a part of the resource indicated by the byte range is returned. Not for pagination, where a normal 200 should be used. Might be useful in rare cases, but most APIs don’t need this.
207	Multi-Status	Use for batch or bulk requests where the response contains status for multiple parts. Typically used with POST or DELETE.
Redirection Codes
301	Moved Permanently		This and all future requests should be directed to the given URI. Not recommended for APIs as redirection codes are generally not used.
302	Found		Temporary redirect; some clients may change the method from POST to GET. Mainly used for dismissing and redirecting form submissions in browsers. Not recommended for APIs.
303	See Other		Indicates that the response can be found under another URI using a GET method. Not recommended for APIs. The original design is for long running task in API. But we already use 202 + Location to replace it, see ../HTTP%20Semantics%209242628693f84e209daf705d397c27db/%5BADP-357%5D%20Long%20running%20job%20e6872e32e7824847b778f11b7fd373db.md.
304	Not Modified	Use for conditional GET or HEAD requests where the resource has not been modified since the provided date or version.
307	Temporary Redirect		Indicates that the resource temporarily resides at another URI, keeping the same method. Not recommended for APIs.
308	Permanent Redirect		Indicates that the resource permanently resides at another URI, keeping the same method. Not recommended for APIs.
Client Side Error Codes
400	Bad Request	Use for syntactically incorrect or malformed requests.
401	Unauthorized	Use when authentication is required and has failed or has not yet been provided. Often means "Unauthenticated."	SHOULD reference common component.responses.UnauthorizedError
403	Forbidden	Use when the client does not have permission to access the resource.	Only document specific cases.
404	Not Found	Use when the requested resource could not be found.	SHOULD reference common component.responses.NotFoundError
405	Method Not Allowed	Use when the HTTP method used is not allowed for the resource.
406	Not Acceptable	Use when the requested resource can only generate content not acceptable according to the Accept headers sent in the request.
407	Proxy Authentication Failed		Rarely used in API
408	Request Timeout		Server times out waiting for the request. Should not be used for APIs.
409	Conflict	Use when the request could not be processed due to a conflict with the current state of the resource.
410	Gone	Use when the resource requested is no longer available and will not be available again.
411	Length Required	Use when the server requires a Content-Length header in the request.
412	Precondition Failed	Use for conditional requests where a precondition is not met. Often used with If-Match for optimistic locking.
413	Payload Too Large	Request headers or body exceed a defined limit. This might happen for large JWT containing many scopes or large HTTP bodies.
415	Unsupported Media Type	Use when the media format of the requested data is not supported by the server.
417	Expectation Failed		Client used an Expect header which the server does not support.
418	I’m a Teapot		Defined as a joke in RFC 2324.
422	Unprocessable Entity		Server understands the content type but cannot process the content. 400 covers most use-cases without a clear benefit to differentiating.
423	Locked	Use when the resource is locked and cannot be accessed. Often used for pessimistic locking.
424	Failed Dependency		Request failed due to failure of a previous request. Not applicable to RESTful APIs. Usually used in WebDAV.
428	Precondition Required	Use when the server requires the request to be conditional, to prevent "lost update" problems.
429	Too Many Requests	Use when the client has sent too many requests in a given amount of time ("rate limiting").
431	Request Header Fields Too Large		Server cannot process the request because the request headers are too large.
Server Side Error Codes
500	Internal Server Error	Use for generic server errors when the server encounters an unexpected condition.
501	Not Implemented	Use when the server does not support the functionality required to fulfill the request.
502	Bad Gateway		Server received an invalid response from an inbound server.
503	Service Unavailable	Use when the server is not ready to handle the request, usually due to maintenance or overload. Client retry may be sensible.
504	Gateway Timeout	Use when the server, while acting as a gateway or proxy, did not receive a timely response from the upstream server.
505	HTTP Version Not Supported		Server does not support the HTTP protocol version used in the request.
507	Insufficient Storage	Server is unable to store the resource as needed to complete the request. Designed for WebDAV in https://datatracker.ietf.org/doc/html/rfc4918#section-11.5
511	Network Authentication Required		Client needs to authenticate to gain network access.

INFO

💡 For 4xx and 5xx response detail, see Error Design.

[ADP-200] HTTP Status

HTTP Status Codes Usage

HTTP Status Codes - Usage Guidelines

References

Design Reference

[ADP-200] HTTP Status ​

HTTP Status Codes Usage ​

HTTP Status Codes - Usage Guidelines ​

References ​

Design Reference ​

[ADP-200] HTTP Status

HTTP Status Codes Usage

HTTP Status Codes - Usage Guidelines

References

Design Reference