Error handling is an important part of designing simple and intuitive APIs. Consistent error handling allows developers to know how to expect to receive errors, and to reduce boilerplate by having common error-handling logic, rather than being expected to constantly add verbose error handling everywhere.
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-reachable identifier in addition to the
code field, changing the
error message must be considered a backwards-incompatible change.
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][https://aip.dev/4221].
- 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.