⚠️
Home/Blog/Technical Writing Course Summary/Error Messages/⚠️General Error Handling Rules

General Error Handling Rules

Don’t Fail Silently

Failure is inevitable; failing to report failures is inexcusable
Failing silently causes the following problems:
  • User Confusion: They may be left wondering why their order didn’t go through.
  • Customer Care: They can’t figure out what’s wrong as they don’t see any errors logged.
Embrace your software’s fallibility and plan error messages during design. Minimize ways for users to misuse your software, but assume it can’t be completely eliminated.

Follow the programming language guides

Toggle to see guides
Follow the guidelines on error handling in Google's programming language guides, including:

Implement the full error model

Implement the full error model described in the Errors page of the Google AIP. The central component is the Status.
package google.rpc;

message Status {
  int32 code = 1; // Error code (defined by google.rpc.Code)
  string message = 2; // Human-readable error message
  repeated google.protobuf.Any details = 3; // Additional error information
}
Instructions
  • Specify an appropriate error message.
  • Specify extra details where necessary.
Example
An error object would look like the following:

{
	code: Status.INVALID_ARGUMENT,
	message: "Unable to add task data into database!",
}
Other Resources
 

Avoid swallowing the root cause

A good example is the case of “Server Errors”. Many different situations can lead to it including:
  • Service failure.
  • Network connection drop.
  • Mismatching status.
  • Permission issues.
Since there could be many different causes, “Server Error” is too broad an error message to help users understand and fix the problem. Try to provide additional context especially when the server logs contain id info about the in-session user and operation.

Log the error codes

Numeric error codes help customer support monitor and diagnose errors. Hence, its quite valuable to specify error codes along with textual error messages.
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.
General error handling rules  |  Technical Writing  |  Google for Developers
Before we get to the fun part of the course—wording error messages—let's
discuss a few general error handling rules.
General error handling rules  |  Technical Writing  |  Google for Developers
https://developers.google.com/tech-writing/error-messages/error-handling
General error handling rules  |  Technical Writing  |  Google for Developers