Handling Errors From the Cloud Support API

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:

  1. Retry the request. Since internal errors are usually transient, retrying your request after a short delay is often effective.
  2. If the issue persists after a reasonable period, refer to Obtaining help when unable to resolve issues with the API. Known, widespread issues are communicated on the Status Dashboard.

Invalid argument errors

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:

  1. Carefully examine the error response body. It should contain specific details about the invalid argument, which will guide you in identifying the problem.
  2. Consult the documentation for the specific endpoint you are calling. Pay close attention to the required parameters, their data types, allowed values, and formats.
  3. 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.
  4. Correct the request.
  5. Retry the request.
  6. 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.

Not found errors

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:

  1. 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.
  2. Verify that the resource you are trying to access actually exists, if possible.
  3. Carefully examine the entire API endpoint URL for any spelling mistakes or incorrect characters.
  4. Consider if there could be an underlying authorization problem preventing you from seeing the resource. See Permission denied errors for help with troubleshooting this.
  5. Retry the request.
  6. 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.

Permission denied errors

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:

  1. 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.

  2. 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.

  3. Review your application code or curl commands to ensure you are using the correct service account credentials or user account for authentication.

  4. Retry the request.

  5. 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

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.