Stay organized with collections
Save and categorize content based on your preferences.
This guide explains the different types of Cloud Support API errors and how to efficiently resolve them.
Have a backup method to create high priority tickets
Using the Cloud Support API reduces operational complexity by enabling
customers to integrate their trouble ticket system with Google Cloud support. However, in some cases, this might increase technical complexity: either side of the integration
can experience an issue, whether due to a change or due to unexpected data. While
this is rare, it could happen, and it could happen while we're working together
to resolve a production issue.
To be prepared, we recommend having a backup method:
Ensure your incident response team has permission to create P1 support tickets for your production-critical projects directly
in Google Cloud console by following the instructions in
Create and manage support cases.
Ensure that the users of your integration know how and when to escalate to your
incident response team. This may not be obvious. If your integration does not
provide feedback to your users when the integration is experiencing an issue,
then your users may be unaware that their request has not reached Google Support.
Internal errors
Internal errors are indicated by an HTTP 5XX status code in the response. Internal errors indicate an issue within Google Cloud. These errors are typically transient and cannot be corrected by changing your request.
Recommended action:
Retry the request. Since internal errors are usually transient, retrying your request after a short delay is often effective.
Invalid argument errors are indicated by an HTTP 400 Bad Request status code in the response. Invalid argument errors indicate that the request sent to the Cloud Support API was malformed or contained invalid data.
Common causes:
Request didn't include a mandatory parameter, such as the ID of a case.
Providing a value of the wrong type (e.g., sending a string when an integer is expected).
Using an incorrect format for dates, times, or other structured data.
Providing values that are outside the allowed range for a particular parameter.
Misspelling parameter or field names in the request.
Recommended action:
Carefully examine the error response body. It should contain specific details about the invalid argument, which will guide you in identifying the problem.
Consult the documentation for the specific endpoint you are calling. Pay close attention to the required parameters, their data types, allowed values, and formats.
Double-check your request to ensure all required parameters are present, are of the correct type, and adhere to the specified format and value constraints.
Not found errors are indicated by the HTTP 404 Not Found status code in the response. Not found errors indicate that the Cloud Support API couldn't find the specific resource you requested. This usually means that the resource identifier in your request (e.g., an attachment ID, resource name) is incorrect or the resource does not exist. It can also mean that you don't have access to a resource.
Common causes:
Using an invalid or misspelled resource identifier (e.g., attachment ID, resource name).
Attempting to access a resource that does not exist.
Sometimes, a 404 Not Found might be returned instead of a 403 Forbidden to avoid revealing information about the existence of a resource to unauthorized users. However, for "Not Found" errors, focus on resource identifiers and URLs first.
Recommended action:
Double-check the resource identifiers (e.g., attachment ID, resource name) in your request. Ensure they are spelled correctly, have the correct format, and are the identifiers for the resource you intend to access.
Verify that the resource you are trying to access actually exists, if possible.
Carefully examine the entire API endpoint URL for any spelling mistakes or incorrect characters.
Consider if there could be an underlying authorization problem preventing you from seeing the resource. See Permission denied errors for help with troubleshooting this.
Permission denied errors are indicated by an HTTP 403 Forbidden status code in the response. Permission denied errors indicate that you are trying to perform an action that you are not authorized to do or that you are trying to access a resource that does not exist. This usually means that the service account or user you are using to call the Cloud Support API lacks the necessary IAM permissions for the specific operation.
Common causes:
The service account or user you are using to call the API may not have been granted the necessary IAM roles. To grant them, see Access Control and IAM Roles.
IAM roles can be granted at different levels in the Google Cloud resource hierarchy (organization, folder, project). The Cloud Support API supports the organization and project levels, so ensure that the IAM role is granted at the organization level for access to cases on organizations and their projects or the project level for access on a specific project.
You might be unintentionally using a different service account or user than the one you configured with the necessary IAM roles. This can happen if your application is running in an environment with multiple sets of credentials, or if you haven't correctly configured authentication.
Recommended action:
Use the IAM tab in Google Cloud console to verify the IAM roles granted to your service account or user. Ensure that the output includes either cloudsupport.techSupportViewer or cloudsupport.techSupportEditor (or a custom role with the necessary cloudsupport.* permissions) for your service account.
Ensure that the role you have granted is sufficient for the specific API action you are attempting. For example, if you are trying to create a case, verify that you have the Tech Support Editor role (which includes the cloudsupport.techCases.create permission). The Tech Support Viewer role won't be sufficient for actions that modify data.
Review your application code or curl commands to ensure you are using the correct service account credentials or user account for authentication.
Obtaining help when unable to resolve issues with the API
If you are having trouble resolving errors with the Cloud Support API and require immediate
assistance, you can directly manage support cases in Google Cloud console by following Create and manage support cases.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Handling Errors From the Cloud Support API\n\nThis guide explains the different types of Cloud Support API errors and how to efficiently resolve them.\n\nHave a backup method to create high priority tickets\n----------------------------------------------------\n\nUsing the Cloud Support API reduces operational complexity by enabling\ncustomers to integrate their trouble ticket system with Google Cloud support. However, in some cases, this might increase technical complexity: either side of the integration\ncan experience an issue, whether due to a change or due to unexpected data. While\nthis is rare, it could happen, and it could happen while we're working together\nto resolve a production issue.\n\nTo be prepared, we recommend having a backup method:\n\n- Ensure your incident response team has permission to create P1 support tickets for your production-critical projects directly\n in Google Cloud console by following the instructions in\n [Create and manage support cases](/support/docs/customer-care-procedures).\n\n- Ensure that the users of your integration know how and when to escalate to your\n incident response team. This may not be obvious. If your integration does not\n provide feedback to your users when the integration is experiencing an issue,\n then your users may be unaware that their request has not reached Google Support.\n\nInternal errors\n---------------\n\nInternal errors are indicated by an HTTP `5XX` status code in the response. Internal errors indicate an issue within Google Cloud. These errors are typically transient and cannot be corrected by changing your request.\n\nRecommended action:\n\n1. Retry the request. Since internal errors are usually transient, retrying your request after a short delay is often effective.\n2. If the issue persists after a reasonable period, refer to [Obtaining help when unable to resolve issues with the API](#obtaining_help_when_unable_to_resolve_issues_with_the_api). Known, widespread issues are communicated on the [Status Dashboard](https://status.cloud.google.com).\n\nInvalid argument errors\n-----------------------\n\nInvalid argument errors are indicated by an HTTP `400 Bad Request` status code in the response. Invalid argument errors indicate that the request sent to the Cloud Support API was malformed or contained invalid data.\n\nCommon causes:\n\n- Request didn't include a mandatory parameter, such as the ID of a case.\n- Providing a value of the wrong type (e.g., sending a string when an integer is expected).\n- Using an incorrect format for dates, times, or other structured data.\n- Providing values that are outside the allowed range for a particular parameter.\n- Misspelling parameter or field names in the request.\n\nRecommended action:\n\n1. Carefully examine the error response body. It should contain specific details about the invalid argument, which will guide you in identifying the problem.\n2. Consult the documentation for the specific endpoint you are calling. Pay close attention to the required parameters, their data types, allowed values, and formats.\n3. Double-check your request to ensure all required parameters are present, are of the correct type, and adhere to the specified format and value constraints.\n4. Correct the request.\n5. Retry the request.\n6. If the issue persists, and you're confident that your request is valid, refer to [Obtaining help when unable to resolve issues with the API](#obtaining_help_when_unable_to_resolve_issues_with_the_api).\n\nNot found errors\n----------------\n\nNot found errors are indicated by the HTTP `404 Not Found` status code in the response. Not found errors indicate that the Cloud Support API couldn't find the specific resource you requested. This usually means that the resource identifier in your request (e.g., an attachment ID, resource name) is incorrect or the resource does not exist. It can also mean that you don't have access to a resource.\n\nCommon causes:\n\n- Using an invalid or misspelled resource identifier (e.g., attachment ID, resource name).\n- Attempting to access a resource that does not exist.\n- Sometimes, a `404 Not Found` might be returned instead of a `403 Forbidden` to avoid revealing information about the existence of a resource to unauthorized users. However, for \"Not Found\" errors, focus on resource identifiers and URLs first.\n\nRecommended action:\n\n1. Double-check the resource identifiers (e.g., attachment ID, resource name) in your request. Ensure they are spelled correctly, have the correct format, and are the identifiers for the resource you intend to access.\n2. Verify that the resource you are trying to access actually exists, if possible.\n3. Carefully examine the entire API endpoint URL for any spelling mistakes or incorrect characters.\n4. Consider if there could be an underlying authorization problem preventing you from *seeing* the resource. See [Permission denied errors](#permission_denied_errors) for help with troubleshooting this.\n5. Retry the request.\n6. If the issue persists, but you are certain that the resource identifiers are correct and the resource should exist, refer to [Obtaining help when unable to resolve issues with the API](#obtaining_help_when_unable_to_resolve_issues_with_the_api).\n\nPermission denied errors\n------------------------\n\nPermission denied errors are indicated by an HTTP `403 Forbidden` status code in the response. Permission denied errors indicate that you are trying to perform an action that you are not authorized to do or that you are trying to access a resource that does not exist. This usually means that the service account or user you are using to call the Cloud Support API lacks the necessary IAM permissions for the specific operation.\n\nCommon causes:\n\n- The service account or user you are using to call the API may not have been granted the necessary IAM roles. To grant them, see [Access Control and IAM Roles](/support/docs/reference/v2#access_control_and_iam_roles).\n- IAM roles can be granted at different levels in the Google Cloud resource hierarchy (organization, folder, project). The Cloud Support API supports the organization and project levels, so ensure that the IAM role is granted at the organization level for access to cases on organizations and their projects or the project level for access on a specific project.\n- You might be unintentionally using a different service account or user than the one you configured with the necessary IAM roles. This can happen if your application is running in an environment with multiple sets of credentials, or if you haven't correctly configured authentication.\n\nRecommended action:\n| **Important:** IAM permission changes can sometimes take a few minutes to propagate fully through Google Cloud's systems. If you have just granted a new role, wait a short period (e.g., 5-10 minutes) before retrying your API call to allow time for the permissions to take effect.\n\n1. Use the IAM tab in Google Cloud console to verify the IAM roles granted to your service account or user. Ensure that the output includes either `cloudsupport.techSupportViewer` or `cloudsupport.techSupportEditor` (or a custom role with the necessary `cloudsupport.*` permissions) for your service account.\n\n2. Ensure that the role you have granted is sufficient for the specific API action you are attempting. For example, if you are trying to create a case, verify that you have the `Tech Support Editor` role (which includes the `cloudsupport.techCases.create` permission). The `Tech Support Viewer` role won't be sufficient for actions that modify data.\n\n3. Review your application code or curl commands to ensure you are using the correct service account credentials or user account for authentication.\n\n4. Retry the request.\n\n5. If the issue persists, refer to [Obtaining help when unable to resolve issues with the API](#obtaining_help_when_unable_to_resolve_issues_with_the_api).\n\nObtaining help when unable to resolve issues with the API\n---------------------------------------------------------\n\nIf you are having trouble resolving errors with the Cloud Support API and require immediate\nassistance, you can directly manage support cases in Google Cloud console by following [Create and manage support cases](/support/docs/customer-care-procedures)."]]
