5xx response

As explained in The Design of Web APIs, Second Edition

A 5xx status class is the class of HTTP status codes indicating that the server failed to fulfill an otherwise valid request.

A 5xx response indicates that the server failed to fulfill an otherwise valid request because of an unexpected implementation problem or planned unavailability. Codes from 500 through 599 identify the provider as responsible. section 4.5.1

Use 5xx responses to classify provider-side failures:

• Return 500 Internal Server Error for unexpected server errors, such as a null pointer exception or inaccessible database server. section 4.5.1 section 4.9
• Distinguish provider failures from 4xx consumer errors and 2xx successful operations. section 4.5.1 section 4.5.2
• Prefer assigned, commonly used status codes; avoid custom or unassigned codes that create compatibility problems. 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.

The status-class diagram connects a numeric code and human-readable reason with success or error responsibility. section 4.5.1

How The Design of Web APIs, Second Edition covers it

How deep it goes

Explains the class boundary, causes, selection rationale, and 500 fallback, but does not detail individual 5xx codes.

Examples

Uses null pointer exceptions, inaccessible database servers, planned unavailability, and 500 Internal Server Error.

What it assumes

Assumes familiarity with HTTP requests and responses while establishing status-code classes and consumer-provider responsibility.

What you can do after

Evaluate whether an API outcome is a provider error and select 500 Internal Server Error for unexpected failures.

How it connects

Contrasts 5xx responses with 2xx success responses, 4xx client errors, HTTP methods, and the IANA status code registry.

liveBookmanning.com

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

Related concepts

• 4xx responsecontrasts with · A 4xx response is an HTTP response with a status code from 400 through 499 indicating that the client’s request contains an error or cannot be fulfilled as submitted.
• failuremeasures · A failure is an unsuccessful outcome or condition in which an operation, process, or system does not achieve an expected result.
• alertingused by · Alerting is the generation and delivery of notifications when monitored conditions or events meet defined criteria or require attention or action.

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.