Skip to content
AEP

Errors

Effective error communication is an important part of designing simple and intuitive APIs. Services returning standardized error responses enable API clients to construct centralized common error handling logic. This common logic simplifies API client applications and eliminates the need for cumbersome custom error handling code.

Guidance

Services must clearly distinguish successful responses from error responses.

The structure of the error response must be consistent across all APIs of the service. You should use the error response structure below which comes from the Problem Details for HTTP APIs RFC 9457.

Structure

An error response should contain the following fields:

NameTypeRequiredDescription
typestringYA URI reference URI that identifies the problem type. If the type URI is a locator (e.g., those with an “http” or “https” scheme), dereferencing it SHOULD provide human-readable documentation for the problem type.
statusintegerThe HTTP status code that best describes the type of problem detected.
titlestringA human-readable description of the problem. Messages are likely to be logged in plain text and must not include information about a specific occurrence nor any sensitive data like PII. Information about specific occurrences should be part of metadata.
detailstringA human-readable explanation specific to this occurrence of the problem. This may contain PII and should not be logged.
instancestringA unique identifier for the specific occurrence of the problem.

An error response may contain additional fields appropriate for a specific error type.

The error title and detail fields should help a reasonably technical user understand and resolve the issue, and should not assume that the user is an expert in your particular API. Additionally, the error title and detail must not assume that the user will know anything about its underlying implementation.

The error detail should be brief but actionable. Any extra information should be provided in additional properties. If even more information is necessary, you should provide a link where a reader can get more information or ask questions to help resolve the issue.

The error detail field

  • is a developer-facing, human-readable “debug message”.
  • both explains the error and offers an actionable resolution to it.
  • value may significantly change over time for the same error, and should not be string-matched by any clients to determine the error.

All human-readable error details returned by the service must use the same language.

A JSON representation of an error response might look like the following:

{
  "type": "RESOURCE_EXHAUSTED",
  "status": 429,
  "title": "Too Many Requests",
  "detail": "The zone 'us-east1-a' does not have enough resources available to fulfill the request. Try a different zone, or try again later.",
  "instance": "7934df3e-4b63-429b-b0f5-b8d350ec165e"
}

Services must return a google.rpc.Status message when an API error occurs, and must use the canonical error codes defined in google.rpc.Code. More information about the particular codes is available in the gRPC status code documentation.

The error response structure defined above should be returned in the details field of the Status message. Services should use the aep.api.ProblemDetails to define this field.

Dynamic variables

The best, actionable error detail includes dynamic segments. These variable parts of the message are specific to a particular request. Consider the following example:

The Book, “The Great Gatsby”, is unavailable at the Library, “Garfield East”. It is expected to be available again on 2199-05-13.

The preceding error detail is made actionable by the context, both that originates from the request, the title of the Book and the name of the Library, and by the information that is known only by the service, i.e. the expected return date of the Book.

All dynamic variables found in error detail must also be present as additional properties of the error response

bookTitle: 'The Great Gatsby'
library: 'Garfield East'
expectedReturnDate: '2199-05-13'

Once present for a particular error type, additional properties must continue to be included in the the error response to be backwards compatible, even if the value for a particular property is empty.

Localization

The title and detail fields should be presented in the service’s native language. If a localized detail is required, it may be included as an additional property in the error response, and should be named localizedDetail.

Partial errors

APIs should not support partial errors. Partial errors add significant complexity for users, because they usually sidestep the use of error codes, or move those error codes into the response message, where the user must write specialized error handling logic to address the problem.

However, occasionally partial errors are necessary, particularly in bulk operations where it would be hostile to users to fail an entire large request because of a problem with a single entry.

Methods that require partial errors should use long-running operations, and the method should put partial failure information in the metadata message. The errors themselves must still be represented as an error object as described in this AEP.

Permission Denied

If the user does not have permission to access the resource or parent, regardless of whether or not it exists, the service must error with PERMISSION_DENIED (HTTP 403). Permission must be checked prior to checking if the resource or parent exists.

If the user does have proper permission, but the requested resource or parent does not exist, the service must error with NOT_FOUND (HTTP 404).

Rationale

Further reading

Changelog