Troubleshooting API usage

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

Background

Google APIs are networked APIs provided by Google services. Applications can access Google APIs via JSON HTTP and gRPC from different environments. We recommend developers to use Google-provided client libraries in their applications. These libraries implement common boilerplate logic, such as authentication and list pagination, which greatly reduce 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 lets 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, higher 400 errors can mean a recently updated application has some logical bugs, or higher request and response sizes can cause slower application performance.

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 application developers log API errors on the client side. You can either log the errors to a local storage or to a remote logging API, such as 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 retry after 503 errors or re-authenticate users after 401 errors.

  • The error message lets application developers understand the error and fix their application logic.

  • The error details contain additional information the applications can use to handle the error programmatically.

For more information, see the Errors page.