API error best practices

Communicate problems their resolution when processing API requests.

Problem statement

API errors can occur due to various reasons such as invalid requests, authentication issues, or problems with the server.

Errors are one of the feedback mechanisms developer rely upon during development to ensure their integration fulfills all requirements and edge cases. Poor error responses can contribute to longer development times and a less reliable service in production. This is especially true for developers who learn by doing and approach new APIs with a trial-and-error strategy.

Sometimes a end user needs to be prevented from completing their current task due to legitimate business policies. In these situations, it is important to maintain the end user's trust and provide them with a recourse if possible. Great errors are therefore not just the final state of a user journey, but can be the beginning of a new one.

The status code of a HTTP response usually does not communicate enough information to the developer or end user to be able to understand and resolve the underlying issue. Therefore it is incumbent on API providers to supply clear and helpful information in the response body.

Success criteria

Since errors are a critical source of feedback to developers, their quality directly impacts developer experience.

Product requirements

A good error error response satisfies four use cases:

1. Provides the developer with a human-readable message for troubleshooting.
2. Encodes the type of error as a stable identifier that can be read programatically.
3. Includes all dynamic information relevant to the error instance as machine-readable variables.
4. Includes a localized message that may be shown verbatim to the end user.

User stories

As a developer, I want error responses to contain a distinct code for each possible failure, so that my integration can handle all foreseeable scenarios in production.Functional

Most REST APIs build upon the standard HTTP status codes to provide additional semantics relevant to the business domain. This usually takes the form of an additional JSON field in the response body.

Documenting each failure mode upfront allows application developers to craft tailored experiences for each scenario, if they wish. Of course, application developers should still build a generic, catch-all flow.

As a developer, I want error responses to contain structured, machine-readable information describing the particular instance of the problem, so that my application can streamline the error-recovery experience for end users.Functional

Using the example of an invalid request error, an error response should describe which fields were invalid and why to the client. If this information is structured in a machine-readable format, the client application can provide an experience that is tailored to the error, for example by highlighting and focussing the inputs for the invalid fields in the interface.

As a developer, I want error responses to contain a descriptive message, so that I can immediately understand what went wrong without having to consult the API's documentation.Developer Experience

All errors should provide a human readable description of the problem in the response body. This aids developers during the development and testing phases. Logging systems typically also include this message as part of the log record.

Include as much information as practible, without disclosing sensitive information.

As a customer support agent, I want error responses to contain a unique trace identifier, so that I can correlate errors encountered by customers with specific logs and transactions in the system.Operations

Occasionally an end user will need to contact support in order to troubleshoot or resolve an error that occured. Providing a trace identifier can often expediate this process by allowing support agents and engineers to immediately identify the transaction where the error occured.

As a developer, I want error responses to contain a localized message, so that my application's catch-all error handler can still provide an informative message to the end user.Developer Experience

The primary message included in an error response is usually intended for the developer integrating the API. As such, it is less suited for the end user and may come across as cryptic, confusing or off-putting.

By including a localized error message intended for the end user in error responses, you can make an API simpler to integrate against as the developer no longer has to choose between writing a message for each error code or relying on an unhelpful, generic message.

As a SecOps team, I want error responses to exclude sensitive information, so that I can avoid potential security vulnerabilities.Security

API errors should provide further detail about the API contract to the client. They should not be used to debug the server implementation. Take care not to include implementation details such as stack traces or pass through error messages from third-party frameworks.

As an API owner, I want to log and monitor API errors, so that I can fix recurring issues.Analytics

Logging and monitoring API errors allows API owners to track and analyze patterns, enabling them to make data-driven decisions to enhance the API's performance and stability.

Explore design patterns