Stay organized with collections
Save and categorize content based on your preferences.
Before we get to the fun part of the course—wording error messages—let's
discuss a few general error handling rules.
Don't fail silently
Failure is inevitable; failing to report failures is inexcusable.
Failing silently causes the following problems:
Users wonder whether something has gone wrong. ("Why did my order not go
through?")
Customer support wonders what caused a problem. ("The log file gave no
indication of a problem.")
Embrace your software's fallibility. Assume that humans will make mistakes
using your software. Try to minimize ways for people to misuse your software,
but assume that you can't completely eliminate misuse. Therefore, plan error
messages as you design software.
Follow the programming language guides
Follow the guidelines on error handling in Google's programming language guides,
including:
Implement the full error model described in the Errors page of the Google
AIP.
For instance, note the following quote
about implementing error messages in services:
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.
API implementations should not swallow the root cause of issues occurring in
the back end. For example, many different situations can cause a
"Server error" problem, including:
service failure
network connection drop
mismatching status
permission issues
"Server error" is too general an error message to
help users understand and fix the problem. If the server logs contain
identification information about the in-session user and operation, we recommend
providing additional context on the particular failure case.
Log the error codes
Numeric error codes help customer support monitor and diagnose errors.
Consequently, specifying numeric error codes along with textual error messages is often
quite valuable.
You can specify error codes for both internal and external errors.
For internal errors, provide a proper error code for easy lookup/debugging
by internal support personnel and engineers.
Document all error codes.
Raise errors immediately
Raise errors as early as useful. Holding on to errors and then raising them
later increases debugging costs dramatically.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-03-31 UTC."],[[["\u003cp\u003eAlways report errors instead of failing silently to provide users and support with crucial information.\u003c/p\u003e\n"],["\u003cp\u003eAdhere to Google's programming language guides for consistent and effective error handling practices.\u003c/p\u003e\n"],["\u003cp\u003eImplement a comprehensive error model, including standardized error codes and messages, as outlined in Google AIP.\u003c/p\u003e\n"],["\u003cp\u003eProvide specific and informative error messages that reveal the root cause of the issue rather than generic ones.\u003c/p\u003e\n"],["\u003cp\u003eLog error codes, both internal and external, and document them thoroughly for efficient monitoring and debugging.\u003c/p\u003e\n"],["\u003cp\u003eRaise errors immediately upon detection to simplify debugging and prevent delayed issue discovery.\u003c/p\u003e\n"]]],["Software should report all failures, avoiding silent failures that confuse users and hinder support. Follow programming language guidelines for error handling, such as those in Google's style guides, and implement the full error model as described in the Google API design. Avoid generic errors like \"Server error\"; provide specific details. Implement numeric error codes for internal and external use and log them for monitoring and debugging. Raise errors promptly to ease troubleshooting.\n"],null,["# General error handling rules\n\n\u003cbr /\u003e\n\nBefore we get to the fun part of the course---wording error messages---let's\ndiscuss a few general error handling rules.\n\nDon't fail silently\n-------------------\n\nFailure is inevitable; failing to report failures is inexcusable.\nFailing silently causes the following problems:\n\n- Users wonder whether something has gone wrong. (*\"Why did my order not go\n through?\"*)\n- Customer support wonders what caused a problem. (*\"The log file gave no\n indication of a problem.\"*)\n\nEmbrace your software's fallibility. Assume that humans will make mistakes\nusing your software. Try to minimize ways for people to misuse your software,\nbut assume that you can't completely eliminate misuse. Therefore, plan error\nmessages as you design software.\n\nFollow the programming language guides\n--------------------------------------\n\nFollow the guidelines on error handling in Google's programming language guides,\nincluding:\n\n- [Google C++ Style\n Guide](https://google.github.io/styleguide/cppguide.html)\n- [Google Java Style\n Guide](https://google.github.io/styleguide/javaguide.html)\n- [Google Python Style\n Guide](https://google.github.io/styleguide/pyguide.html), particularly the [Error\n Messages section](https://google.github.io/styleguide/pyguide.html#3102-error-messages)\n- [Google JavaScript Style\n Guide](https://google.github.io/styleguide/jsguide.html)\n- [Google Go Style\n Guide](https://google.github.io/styleguide/go), particularly the [Error handling\n section](https://google.github.io/styleguide/go/best-practices#error-handling)\n\nImplement the full error model\n------------------------------\n\nImplement the full error model described in the [Errors page of the Google\nAIP.](https://google.aip.dev/193)\nFor instance, note the following quote\nabout implementing error messages in services:\n\u003e Services must return a [google.rpc.Status](https://github.com/googleapis/api-common-protos/blob/master/google/rpc/status.proto) message when an API error occurs, and must use the canonical error codes defined in [google.rpc.Code](https://github.com/googleapis/api-common-protos/blob/master/google/rpc/code.proto).\n\nThe [Errors page of the Google Cloud API design\nguide](https://cloud.google.com/apis/design/errors) provides helpful information about implementing the full error\nmodel for Google APIs.\n\nAvoid swallowing the root cause\n-------------------------------\n\nAPI implementations should not swallow the root cause of issues occurring in\nthe back end. For example, many different situations can cause a\n\"Server error\" problem, including:\n\n- service failure\n- network connection drop\n- mismatching status\n- permission issues\n\n\"Server error\" is too general an error message to\nhelp users understand and fix the problem. If the server logs contain\nidentification information about the in-session user and operation, we recommend\nproviding additional context on the particular failure case.\n\nLog the error codes\n-------------------\n\nNumeric **error codes** help customer support monitor and diagnose errors.\nConsequently, specifying numeric error codes along with textual error messages is often\nquite valuable.\n\nYou can specify error codes for both internal and external errors.\nFor internal errors, provide a proper error code for easy lookup/debugging\nby internal support personnel and engineers.\n\nDocument all error codes.\n\nRaise errors immediately\n------------------------\n\nRaise errors as early as useful. Holding on to errors and then raising them\nlater increases debugging costs dramatically.\n\n**Next unit:** [Identify the error's cause](/tech-writing/error-messages/identify-the-cause)"]]
