Troubleshooting API Usage

This page provides application developers an overview of how to troubleshoot their usage of Google APIs and Google Cloud APIs.


Google APIs are networked APIs provided by Google services. Applications can access Google APIs via JSON HTTP and gRPC in different environments. We recommend developers to use Google-provided client libraries in their applications. These libraries implement common boilerplate logic, such as pagination, which greatly reduce the development overhead and common mistakes.

For more information, see Client Libraries Explained

Getting started

If you are new to Google APIs, you should follow the Getting Started page to complete the preparation steps for your application. You should first use the curl -v command to send test requests to Google APIs that you want to use. It will let you experiment with Google APIs without writing any code. You can often resolve many issues before you start real application development.

For more information, see Getting Started.

Troubleshooting using metrics

Google APIs provide free API metrics that cover common aspects of API usage, including request counts, errors, latencies, request and response sizes. They provide fine-grained dimensions in terms of applications and locations. Developers can discover abnormal API usage, and identify potential root causes. For example, error codes higher 400 can mean a recently updated application has some logical bugs, or higher request and response sizes can cause additional system load.

For more information, see Monitoring API usage.

Troubleshooting using logs

For security and privacy reasons, Google APIs generally don't provide API logs to application developers. We highly recommend appliication developers to log API errors on the client side. You can either log the errors to local storage or to the Cloud Logging API.

Logs typically contain more information about errors than metrics, such as error messages and error details. They are extremely useful and often necessary to troubleshoot API errors. When developers notice any issue with their API usage, they can query the logs to find error messages and error details, and use the information to resolve the errors or contact the support.

Cloud Audit Logs

For security sensitive activities, Google Cloud products may generate audit logs that contain detailed information of the activities. They are a great source of information for troubleshooting your usage of Google Cloud APIs. For example, VPC Service Controls dry run feature generates audit logs for administrators to evaluate the upcoming policy changes.

For more information, see Cloud Audit Logs.

Resolving errors

If you have issues with your Google API usage and you have found the corresponding metrics and logs, you can follow API Design Guide Errors page to resolve the errors.

In general, each API error has 3 pieces of information: error code, error message, and error details:

  • The error code lets applications handle the error at the higher level, such as 401 vs 403.
  • The error message lets application developers understand the error and manually fix their application logic. WARNING: Do not code against the error meesages, they are subject to change without notice.
  • The error details contain additional information the applications can use to handle the error programmatically.

For more information, see the Errors page.