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.
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.
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.
ErrorInfo message is the recommended way to send a
Error messages must be in English. If a localized error message is also
required, the service should use
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
- For which error codes to retry, see AIP-194.
- For how to retry errors in client libraries, see AIP-4221.
- 2022-08-12: Reworded/Simplified intro to add clarity to the intent.
- 2020-01-22: Added a reference to the
- 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.