Error Handling

This document identifies the different types of errors that the API can return.

There are a few specific error codes need to be handled with custom logic. Error response encoded in the following format:

{
  "error": {
    "code": 400,
    "message": "The user is already subscribed",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ERROR_CODE_SUBSCRIPTION_REJECTED_ALREADY_SUBSCRIBED",
      }
    ]
  }
}

Retriable HTTP Error Codes

The following http error codes indicate the system is temporarily unavailable, retrying with exponential backoff is recommended.

Error Code Description Client Action
429 Requests are throttled Retry using exponential backoff
503 Service is temporarily unavailable Retry using exponential backoff

Custom Error Code

Custom error code is encoded in ErrorInfo.reason, as in the example above. The possible errors for each API is specified as follows:

partners.subscriptions.create

Error Reason Error type Description Client Action
ERROR_CODE_SUBSCRIPTION_REJECTED_ALREADY_SUBSCRIBED FAILED_PRECONDITION
(400)
End user is already subscribed with Google Consider guiding the user to cancel the subscription on the appropriate Google site first
ERROR_CODE_SUBSCRIPTION_REJECTED_SUBSCRIPTION_INELIGIBLE FAILED_PRECONDITION
(400)
End user is ineligible for the subscription The subscription cannot be activated for the user
ERROR_CODE_SUBSCRIPTION_REJECTED_PROMOTION_INELIGIBLE FAILED_PRECONDITION
(400)
End user is ineligible for the promotion Consider removing the promotion or using another one
ERROR_CODE_PRODUCT_NOT_FOUND NOT_FOUND
(404)
The product isn't found, isn't accessible by the partner, or isn't available in the requested service location A different product or service location must be used
ERROR_CODE_PROMOTION_NOT_FOUND NOT_FOUND
(404)
The promotion isn't found, isn't accessible by the partner, or isn't available in the requested service location A different promotion or service location must be used
ERROR_CODE_SUBSCRIPTION_NOT_FOUND NOT_FOUND
(404)
The subscription to upgrade or downgrade isn't found A different subscription must be used
ERROR_CODE_SUBSCRIPTION_USER_MISMATCH FAILED_PRECONDITION
(400)
The user info in the subscription doesn't match the existing record for upgrade and downgrade Do not retry with the same Google user or partner_user_token
ERROR_CODE_SUBSCRIPTION_DETAILS_MISMATCH FAILED_PRECONDITION
(400)
The subscription details don't match the existing record for upgrade and downgrade Do not retry

partners.subscriptions.provision

Error Reason Error type Description Client Action
ERROR_CODE_SUBSCRIPTION_REJECTED_ALREADY_SUBSCRIBED FAILED_PRECONDITION
(400)
End user is already subscribed with Google Consider guiding the user to cancel the subscription on the appropriate Google site first
ERROR_CODE_SUBSCRIPTION_REJECTED_SUBSCRIPTION_INELIGIBLE FAILED_PRECONDITION
(400)
End user is ineligible for the subscription The subscription cannot be activated for the user
ERROR_CODE_SUBSCRIPTION_REJECTED_PROMOTION_INELIGIBLE FAILED_PRECONDITION
(400)
End user is ineligible for the promotion Consider removing the promotion or using another one
ERROR_CODE_PRODUCT_NOT_FOUND FAILED_PRECONDITION
(400)
The product isn't found, isn't accessible by the partner, or isn't available in the requested service location A different product or service location must be used
ERROR_CODE_PROMOTION_NOT_FOUND FAILED_PRECONDITION
(400)
The promotion isn't found, isn't accessible by the partner, or isn't available in the requested service location A different promotion or service location must be used
ERROR_CODE_SUBSCRIPTION_NOT_FOUND NOT_FOUND
(404)
The subscription to upgrade or downgrade isn't found A different subscription must be used
ERROR_CODE_SUBSCRIPTION_USER_MISMATCH FAILED_PRECONDITION
(400)
The user info in the subscription doesn't match the existing record for upgrade and downgrade Do not retry with the same partner_user_token
ERROR_CODE_SUBSCRIPTION_DETAILS_MISMATCH FAILED_PRECONDITION
(400)
The subscription details don't match the existing record for upgrade and downgrade Do not retry

partners.subscriptions.entitle

Error Reason Error type Description Client Action
ERROR_CODE_SUBSCRIPTION_REJECTED_ALREADY_SUBSCRIBED FAILED_PRECONDITION
(400)
End user is already subscribed with Google via another subscription Consider guiding the user to cancel the subscription on the appropriate Google site first
ERROR_CODE_SUBSCRIPTION_ALREADY_ENTITLED FAILED_PRECONDITION
(400)
The subscription is already entitled to the end user in the request Do not retry
ERROR_CODE_SUBSCRIPTION_ALREADY_ENTITLED_TO_ANOTHER_USER FAILED_PRECONDITION
(400)
The subscription is already entitled to a different user than the one in the request Do not retry
ERROR_CODE_SUBSCRIPTION_REJECTED_SUBSCRIPTION_INELIGIBLE FAILED_PRECONDITION
(400)
End user is ineligible for the subscription The subscription cannot be activated for the user
ERROR_CODE_SUBSCRIPTION_REJECTED_PROMOTION_INELIGIBLE FAILED_PRECONDITION
(400)
End user is ineligible for the promotion Consider canceling the subscription.

partners.subscriptions.extend

Error Reason Error type Description Client Action
ERROR_CODE_SUBSCRIPTION_ALREADY_CANCELLED FAILED_PRECONDITION
(400)
The subscription is already cancelled. Do not retry
ERROR_CODE_SUBSCRIPTION_IS_PROCESSING_REQUEST FAILED_PRECONDITION
(400)
The subscription is already being processed for the requested operation Do not retry
ERROR_CODE_SUBSCRIPTION_IN_REQUESTED_STATE FAILED_PRECONDITION
(400)
The requested operation is already complete Do not retry
ERROR_CODE_SUBSCRIPTION_BAD_STATE FAILED_PRECONDITION
(400)
Subscription is in a state that is not valid for the requested operation Do not retry
ERROR_CODE_SUBSCRIPTION_BAD_PROCESSING_STATE FAILED_PRECONDITION
(400)
Subscription is in progress of another request and not valid for the requested operation The request could be retried
ERROR_CODE_REQUEST_ID_COLLISION FAILED_PRECONDITION
(400)
Request with the same request_id has already been processed Do not retry
ERROR_CODE_SUBSCRIPTION_NOT_FOUND NOT_FOUND
(404)
The subscription to extend isn't found A different subscription must be used

partners.subscriptions.cancel

Error Reason Error type Description Client Action
ERROR_CODE_SUBSCRIPTION_ALREADY_CANCELLED FAILED_PRECONDITION
(400)
Subscription is already cancelled The request could be retried
ERROR_CODE_SUBSCRIPTION_IS_PROCESSING_REQUEST FAILED_PRECONDITION
(400)
The subscription is already being processed for the requested operation Do not retry
ERROR_CODE_SUBSCRIPTION_IN_REQUESTED_STATE FAILED_PRECONDITION
(400)
The requested operation is already complete Do not retry
ERROR_CODE_SUBSCRIPTION_BAD_STATE FAILED_PRECONDITION
(400)
Subscription is in a state that is not valid for the requested operation Do not retry
ERROR_CODE_SUBSCRIPTION_BAD_PROCESSING_STATE FAILED_PRECONDITION
(400)
Subscription is in progress of another request and not valid for the requested operation The request could be retried
ERROR_CODE_SUBSCRIPTION_NOT_FOUND NOT_FOUND
(404)
The subscription to cancel isn't found A different subscription must be used

partners.subscriptions.undoCancel

Error Reason Error type Description Client Action
ERROR_CODE_SUBSCRIPTION_IS_PROCESSING_REQUEST FAILED_PRECONDITION
(400)
The subscription is already being processed for the requested operation do not retry
ERROR_CODE_SUBSCRIPTION_IN_REQUESTED_STATE FAILED_PRECONDITION
(400)
The requested operation is already complete Do not retry
ERROR_CODE_SUBSCRIPTION_BAD_STATE FAILED_PRECONDITION
(400)
Subscription is already cancelled and cannot be undone Do not retry
ERROR_CODE_SUBSCRIPTION_BAD_PROCESSING_STATE FAILED_PRECONDITION
(400)
Subscription is in progress of another request and not valid for the requested operation. The request could be retried
ERROR_CODE_SUBSCRIPTION_ALREADY_CANCELLED FAILED_PRECONDITION
(400)
The subscription is already cancelled and undo cancel cannot be done. Do not retry

Java example

You can extract the custom error code from the ErrorInfo as follows:

try {
  client
    .partners()
    .subscriptions()
    .entitle("partners/partnerId/subscriptions/subscriptionId",
        new GoogleCloudPaymentsResellerSubscriptionV1EntitleSubscriptionRequest())
    .setAccessToken(credential.getAccessToken())
    // It is important to overwrite the parameter: &.xgafv=2.
    // Otherwise, the legacy API mode is used by default, where error details
    // are trimmed off for compatibility.
    .set$Xgafv("2");
    .execute();
} catch (GoogleJsonResponseException e) {
    // process error reason by decoding e.getDetails().
  }
}