AIP-193

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 appications and eliminates the need for cumbersome custom error handling code.

Guidance

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.

Error messages 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, error messages must not assume that the user will know anything about its underlying implementation.

Error messages should be brief but actionable. Any extra information should be provided in the details field. 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.

Details

Google defines a set of standard detail payloads for error details, which cover most common needs for API errors. Services should use these standard details payloads when feasible.

Structured details with machine-readable identifiers must be used if users will need to write code against a specific aspect of the error. Error message strings may change over time; however, if an error message does not have a machine-readable identifier in addition to the code field, changing the error message must be considered a backwards-incompatible change.

Note: The ErrorInfo message is the recommended way to send a machine-readable identifier.

Localization

Error messages must be in English. If a localized error message is also required, the service should use google.rpc.LocalizedMessage as the details field.

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 with a google.rpc.Status object.

Further reading

  • For which error codes to retry, see AIP-194.
  • For how to retry errors in client libraries, see AIP-4221.

Changelog

  • 2022-08-12: Reworded/Simplified intro to add clarity to the intent.
  • 2020-01-22: Added a reference to the ErrorInfo message.
  • 2019-10-14: Added guidance restricting error message mutability to if there is a machine-readable identifier present.
  • 2019-09-23: Added guidance about error message strings being able to change.