[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-09 (世界標準時間)。"],[],[],null,["# Troubleshoot the Monitoring API\n\nThis guide explains some of the issues that might arise when you use\nthe Monitoring API.\n\nThe Monitoring API is one of the set of Cloud APIs.\nThese APIs share a common set of error codes. For a list of the error\ncodes defined by the Cloud APIs and general suggestions on\nhandling the errors, see [Handling errors](/apis/design/errors#handling_errors).\n\nUse APIs Explorer for debugging\n-------------------------------\n\nAPIs Explorer is a widget built into the reference pages for API methods.\nIt lets you invoke the method by filling out fields; it doesn't require you\nto write code.\n\nIf you are having trouble with a method invocation, use the APIs Explorer\n(**Try this API** ) widget on the reference page for that method to\ndebug your problem. For more information, see\n[APIs Explorer](/monitoring/api/apis-explorer).\n\nGeneral API errors\n------------------\n\nHere are some of the Monitoring API errors and messages you might\nsee from your API calls:\n\n- `404 NOT_FOUND` with \"The requested URL was not found on this server\":\n Some part of the URL is incorrect. Compare the URL against\n the URL for the method shown on the method's reference page.\n This error might mean that there is a spelling error,\n such as \"project\" instead of \"projects\", or a capitalization error,\n such as \"TimeSeries\" instead of \"timeSeries\".\n\n- `401 UNAUTHENTICATED` with \"User is not authorized to access the project\n (or metric)\": This error code typically indicate an authorization problem,\n but it can mean that there is an error in the project ID or metric type\n name. Verify the spelling and capitalization.\n\n\n If you aren't using APIs Explorer, then try using it. When your API\n call works in APIs Explorer, there is probably an authorization\n issue in the environment where you're making the API call. Go to the\n [API manager page](https://console.cloud.google.com/apis/enabled) to verify\n that the Monitoring API is enabled for your project.\n- `400 INVALID_ARGUMENT` with \"Field filter had an invalid value\": Verify the\n spelling and formatting of the monitoring filter. For more information, see\n [Monitoring Filters](/monitoring/api/v3/filters).\n\n- `400 INVALID_ARGUMENT` with \"Request was missing field interval.endTime\":\n You see this message when the end time missing, or when it is present but\n not properly formatted.\n If you are using APIs Explorer, then don't quote the value of the time\n field.\n\n\n Here are some examples of valid time specifications: \n\n ```\n 2024-05-11T01:23:45Z\n 2024-05-11T01:23:45.678Z\n 2024-05-11T01:23:45.678+05:00\n 2024-05-11T01:23:45.678-04:30\n ```\n\nMissing results\n---------------\n\nWhen an API call returns the status code `200` and an empty response, consider\nthe following:\n\n- 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.\n\n\u003c!-- --\u003e\n\n- When working with a custom metric, verify that that the project which defines the metric is specified.\n\nThere are several reasons why data points might be missing when you use the\n[`timeSeries.list`](/monitoring/api/ref_v3/rest/v3/projects.timeSeries/list) method:\n\n- The data might have aged out.\n For more information, see [Data retention](/monitoring/quotas#data_retention_policy).\n\n- The data might not have propagated to Monitoring yet.\n For more information, see [Latency of metric data](/monitoring/api/v3/latency-n-retention).\n\n- The interval is invalid:\n\n - Verify that the end time is correct.\n - 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](/monitoring/custom-metrics/reading-metrics#time_intervals).\n\nRetrying API errors\n-------------------\n\nTwo of the Cloud APIs error codes indicate circumstances in\nwhich it might be useful to retry the request:\n\n- `503 UNAVAILABLE`: retries are useful when the problem is a short-lived or transient condition.\n- `429 RESOURCE_EXHAUSTED`: retries are useful, after a delay, for long-running background jobs with time-based quota such as *n* calls per *t* seconds. Retries aren't useful when the problem is a short-lived or transient condition, or when you've exhausted a volume-based quota. For transient conditions, consider tolerating the failure. For quota-related issues, consider reducing your quota usage or requesting a quota increase.\n\nWhen writing code that might retry requests, first ensure that the request\nis safe to retry.\n\n### Is the request safe to retry?\n\nIf your request is idempotent, then it is safe to retry. An *idempotent*\naction is one where any change in state does not depend on the current state.\nFor example:\n\n- Reading *x* is idempotent; there is no change to the value.\n- Setting *x* to 10 is idempotent; this might change the state, if the value isn't already 10, but it doesn't matter what the current value is. And it doesn't matter how many times you attempt to set the value.\n- Incrementing *x* is *not* idempotent; the new value depends on the current value.\n\n### Retry with exponential backoff\n\nWhen implementing code to retry requests, you don't want to rapidly issue\nnew requests indefinitely. If a system is overloaded, this approach\ncontributes to the problem.\n\nInstead, use a *truncated exponential backoff* approach.\nWhen requests fail because of transient overloads rather than true\nunavailability, the solution is reduce the load. A truncated exponential\nbackoff follows this general pattern:\n\n- Establish how long you are willing to wait while retrying or how\n many attempts you are willing to make. When this limit is exceeded,\n consider the service unavailable and handle that\n condition appropriately for your application. This is what makes\n the backoff *truncated*; you stop retrying at some point.\n\n- Retry the request with increasingly long pauses to *back off* the\n frequency of retries. Retry until the request succeeds or your\n established limit is reached.\n\n The interval is typically increased by some function of the power of\n the retry count, making it an *exponential* backoff.\n\nThere are many ways to implement an exponential backoff.\nThe following is an example that adds an increasing backoff delay\nto a minimum delay of 1000ms. The initial backoff delay is 2ms, and it\nincreases to 2^*retry_count*^ms with each attempt.\n\nThe following table shows the retry intervals using the initial values:\n\n- Minimum delay = 1s = 1000ms\n- Initial backoff = 2ms\n\nYou can truncate the retry cycle by stopping either after *n* attempts\nor when the time spent exceeds a reasonable value for your application.\n\nFor more information, see the Wikipedia article\n[Exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)."]]
