An HTTP response code is a three-digit number, paired with a descriptive reason, that indicates how the server processed a request. Its class quickly signals the outcome: 2XX means success, 4XX means consumer error, and 5XX means server or implementation error. section 4.5.1
Choose a code by considering the output type, who caused an error, and the request method. Prefer commonly used, assigned codes; unusual or custom codes can surprise consumers and create compatibility problems. section 4.5.2
Common operation outcomes include:
- Return 201 Created after successfully creating a resource. section 4.5.10
- Return 200 OK for successful reads and searches. section 4.5.10
- Return 200 OK for an update when the updated resource is included; return 204 No Content when it is not. section 4.5.10
- Return 204 No Content after a deletion without status data, or 200 OK when status data is returned. section 4.5.10
- Handle missing or invalid input with 400 Bad Request, missing path resources with 404 Not Found, and unexpected failures with 500 Internal Server Error. section 4.5.10
Product creation
A POST /products operation can return 201 Created. If it returns no representation, the Location header identifies the new resource so a client can retrieve it with GET. Error responses should include error information because a status code alone often provides insufficient detail. section 4.6.2
Figure 4.12 An HTTP status has a numeric code and human-readable reason. The class system allows for easily identifying whether the code signifies a success or an error and who is at fault.
Use the class system to interpret unfamiliar codes and distinguish successful processing from consumer and server errors. section 4.5.1
A response begins with its status, followed by headers and an optional body. Describe chosen response codes in OpenAPI alongside each operation’s outputs. section 4.6.1 section 6.7
