4xx response

As explained in The Design of Web APIs, Second Edition

A 4xx status class is the class of HTTP status codes indicating that the client request contains an error or cannot be fulfilled as submitted.

A 4xx response indicates that the consumer’s request contains an error or cannot be fulfilled as submitted. The class covers unparsable data, unsupported methods, missing properties, failed business checks, and insufficient rights. Its three-digit code also identifies responsibility even when the exact code is unfamiliar. section 4.5.1

Online Shopping API

Return 404 Not Found when /products/{product reference} identifies no product; do not use 204 No Content, which implies that the product exists without data. Return 400 Bad Request when product information is incorrect or incomplete. section 4.5.8

Choose a 4xx response by considering:

• Whether the consumer caused the failure rather than the provider; provider or implementation failures belong to the 5xx class. section 4.5.1
• The operation, HTTP method, and output; use registered, commonly understood codes and avoid unassigned custom statuses. section 4.5.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 status code and reason phrase together, then interpret the leading digit to identify success or responsibility. section 4.5.1

How The Design of Web APIs, Second Edition covers it

How deep it goes

Defines responsibility and gives 400 and 404 examples, while deferring broader error-code options to later guidance.

Examples

Uses nonexistent products, incorrect product information, 404 Not Found, 400 Bad Request, and 204 No Content as a contrast.

What it assumes

Assumes basic HTTP requests and methods while establishing status codes, classes, and consumer-versus-provider responsibility.

What you can do after

Apply it via HTTP status selection to distinguish consumer errors from provider failures and map common API errors.

How it connects

Connects 4xx responses with HTTP status codes, HTTP methods, 2xx responses, 5xx responses, 400 Bad Request, and 404 Not Found.

liveBookmanning.com

Read The Design of Web APIs, Second Edition on liveBook Get the book at manning.com

Related concepts

• 5xx responsecontrasts with · A 5xx response is an HTTP response with a status code from 500 through 599 indicating that the server failed to fulfill an otherwise valid request.
• failuremeasures · A failure is an unsuccessful outcome or condition in which an operation, process, or system does not achieve an expected result.
• alertingproduces · Alerting is the generation and delivery of notifications when monitored conditions or events meet defined criteria or require attention or action.
• 400 bad requesthas part · HTTP 400 Bad Request is a client-error status code indicating that a server cannot or will not process a request because of an error in the request.

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.