Troubleshoot the Monitoring API

To diagnose API errors, fix metric ingestion rejections, and resolve missing query results when using the Monitoring API, you can use the troubleshooting techniques and error resolutions in this guide.

The Monitoring API is part of Cloud APIs. For a list of shared error codes and general handling recommendations, see Handling errors.

Use APIs Explorer for debugging

APIs Explorer is a widget built into the reference pages for API methods. It lets you invoke the method by filling out fields; it doesn't require you to write code.

If you are having trouble with a method invocation, use the APIs Explorer (Try this API) widget on the reference page for that method to debug your problem. For more information, see APIs Explorer.

General API and authentication errors

This section lists error codes that can be returned by a variety of Monitoring API methods.

401 UNAUTHENTICATED

The 401 UNAUTHENTICATED error code indicates missing, expired, or invalid OAuth2 or IAM credentials.

The two common error messages for this error code are Request is missing required authentication credential and User is not authorized to access the project (or metric).

  • Cause: Missing Authorization: Bearer <token> header, expired OAuth2 or OIDC token, or invalid service account credentials.
  • Resolution: Refresh authentication tokens using Application Default Credentials (ADC) or gcloud auth print-access-token. Also, verify that the service account key is valid.
If you aren't using APIs Explorer, then try using it. When your API call works in APIs Explorer, there is probably an authorization issue in the environment where you're making the API call. Go to the API manager page to verify that the Monitoring API is enabled for your project.

403 PERMISSION_DENIED for project access and billing

The 403 PERMISSION_DENIED error code indicates you don't have the required permissions to perform the requested action.

There are several different error messages that can be paired with this error code. Two common error messages are Billing check failed for project [PROJECT_ID] and Billing account disabled:

  • Cause: Cloud Billing is disabled or suspended on the Google Cloud project. Custom metric ingestion requires an active billing account.
  • Resolution: Link an active Cloud Billing account to the project in the Google Cloud console.

If you receive this error code when writing metric data, then also see 403 PERMISSION_DENIED when writing metric data.

404 NOT_FOUND

The 404 NOT_FOUND error code indicates that the target project ID does not exist, or that the region or location is unrecognized.

The following lists common error messages for this error code:

  • Project [PROJECT_ID] not found

    • Cause: The project specified in the request URI does not exist or has been deleted.
    • Resolution: Check the project ID spelling and verify that the project is active in the Google Cloud console.

  • Unavailable region or location or Unrecognized region or location

    • Cause: The monitored resource location or region label is invalid or unrecognized.
    • Resolution: Use valid Google Cloud region and zone names, such as us-central1 or us-central1-a.

  • The requested URL was not found on this server

    • Cause: The resource path in the URL is incorrect.
    • Resolution: Compare the URL against the URL for the method shown on the method's reference page. This error might mean that there is a spelling error, such as "project" instead of "projects", or a capitalization error, such as "TimeSeries" instead of "timeSeries".

500 INTERNAL, 503 UNAVAILABLE, 504 DEADLINE_EXCEEDED

There are two common error messages for these error codes: Internal error encountered. Please retry after a few seconds and The service is currently unavailable.

  • Cause: Transient backend infrastructure errors, network issues, or internal database partition rebalancing.
  • Resolution: Implement truncated exponential backoff with jitter on retries, starting at 1 second up to 32 seconds. Set RPC client deadlines to 15 seconds or greater. For more information, see Retrying API errors.

Missing results

When an API call returns the status code 200 and an empty response, consider the following:

  • When the call uses a filter, the filter might not have matched anything. The filter match is case-sensitive. To resolve filter problems, start by specifying only one filter component, such as metric.type, and verify that you get results. Add the other filter components one by one to build up your request.
  • When working with a custom metric, verify that the project that defines the metric is specified.

There are several reasons why data points might be missing when you use the timeSeries.list method:

  • The data might have aged out. For more information, see Data retention.

  • The data might not have propagated to Monitoring yet. For more information, see Latency of metric data.

  • The interval is invalid:

    • Verify that the end time is correct.
    • Verify that the start time is correct and that it is earlier than the end time. When the start time is missing or malformed, the API sets the start time to the end time. For GAUGE metrics, this time interval only matches points whose start and end times are exactly the interval's end time. For CUMULATIVE or DELTA metrics, which measure across time intervals, no points are matched. For more information, see Time intervals.

Errors querying metric data

This section provides information about the errors that can occur when you read metric data using a method such as the timeSeries.list method.

400 INVALID_ARGUMENT when querying metric data

The 400 INVALID_ARGUMENT error code indicates some type of client-side validation error. The error message associated with the error code provides more detailed information and is specific to the API method.

For example, when querying metric data, you might get the following messages:

  • Field filter had an invalid value or Field filter had an invalid value of "[FILTER]": [EXPLANATION]

    • Cause: Indicates a problem with the monitoring filter.
    • Resolution: To resolve, verify the filter's spelling and formatting. For more information, see Monitoring filters.

  • Request was missing field interval.endTime or Field interval.endTime had an invalid value

    • Cause: Indicates that the request is missing the end time or that the value is malformed.

    • Resolution: If you are using APIs Explorer, then don't quote the value of the time field. The following are valid formats:

      2026-05-11T01:23:45Z
2026-05-11T01:23:45.678Z
2026-05-11T01:23:45.678+05:00
2026-05-11T01:23:45.678-04:30
```

Errors writing metric data

This section provides information about the errors that can occur when you use the timeSeries.create method to write metric data, including the following:

  • A summary of error codes.
  • A list of error messages associated with each error code. These entries include both a cause and information about resolution. The General API errors also apply to the create method.

If you don't enable data access audit logs for Monitoring, then failures with the timeSeries.create method might be silent. However, you can do the following:

  • Use the Metrics Explorer to get information about error rates. Use the following settings:

    • Metric: monitoring.googleapis.com/api/request_count
    • Filter: method = "google.monitoring.v3.MetricService.CreateTimeSeries"
    • Aggregation: Group by response_code

  • Use the Logs Explorer to query your Admin Activity logs, which the system creates when it attempts to auto-create a metric descriptor and that action fails. To view these log entries, run the following query, after replacing