API Explorer
API Explorer
Introduction
What's New
Appliance Management
Application Data Management
Asset Management
Asset Metadata
Authentication and Authorization
Cloud Disaster Recovery
Compliance
Copy Management
Credentials Management
Discovery
File Level Restore
Installation
Inventory Source Management
Kubernetes Data Management
Licenses Management
Location Management
Log Management
Monitoring
Protection Policies
Recovery and Reuse Management
Remote Service
Search Clusters
Secrets Manager
Server Disaster Recovery
Storage Management
Telemetry Setting
Upgrade
User Security Management
Virtual Machine Data Management
Whitelist Management

Error handling with response code

Error response

An error response that represents an error or failure, either from a nonsuccessful HTTP status, an error while issuing the request, or a failure during the parsing of the response. The error response contains several important properties:

  1. Code: The error response code.
  2. Reason: Represents why this error happens.
  3. Remediation: Describes what to do with this error.

Client error response

400 Bad Request

This response indicates that the server could not understand the request due to invalid syntax, missing required fields, or the request is semantically invalid.

In PowerProtect Data Manager, the API POST /api/v2/credentials requests four parameters:

  1. type: the type of the credential account.
  2. name: credential account name.
  3. username: the username of credential account.
  4. password: the password of credential account.

In this case, providing only three parameters - type, name, and username - while omitting password returns the response code 400 (Bad Request).

curl --request POST 'https://<your-ppdm-ip>:8443/api/v2/credentials' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
{
    "type": "DATADOMAIN",
    "name": "new_cre_name",
    "username": "admin"
}

The response of the API call is similar to:

{
    "code": 400,
    "reason": "The password field cannot be null or empty.",
    "remediation": "Try again with valid parameters in request.",
    "timestamp": 1614147813480,
    "path": "/api/v2/credentials",
    "extendedInfo": null
}

The reason message states “The password field cannot be null or empty.” To fix the error, provide the correct value for the password parameter, like this:

curl --request POST 'https://<your-ppdm-ip>:8443/api/v2/credentials' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
{
    "type": "DATADOMAIN",
    "name": "new_cre_name",
    "username": "admin",
    "password": {password}
}

The response of the API call is similar to:

200 (OK)
[
  {
      "id": "6f870fa2-03b0-4bbc-a216-ef862562a4ac",
      "name": "new_cre_name",
      "username": "admin",
      "password": null,
      "type": "DATADOMAIN",
      "method": null,
      "secretId": "75eb6beb-1189-4ad1-aea9-4defb4f9a23d",
      "internal": false
  }
]

401 Unauthenticated

This response means that the provided credentials are invalid or missing the authentication token.

After logging out of the PowerProtect Data Manager, any API request returns the error code 401. The response of API call is similar to:

401 (Unauthorized)

{
    "reason": "Invalid authentication token: <access-token>",
    "remediation": "The token is invalid or expired. Login again to receive a new authentication token.",
    "code": 401,
    "path": "/api/v2/users",
    "timestamp": 1612426044516
}

From the remediation object states that the login token is invalid or expired. To fix this error, login again, or refresh the authentication token. See the tutorial for authentication and authorization.

403 Forbidden

This response means that the client is authorized, but the request does not have access rights or is unauthorized to perform this request.

PowerProtect Data Manager provides the following roles: admin, user, export-and-recovery-admin. The role information contains the role description and role privileges. Each role provides different privileges.

For example: A user named test with role type user is not authorized to perform a manual backup with API /api/v2/asset-backups.

In the example, the user test logs in to the system, and attempts a manual backup like this:

curl --request POST 'https://<your-ppdm-server>:8443/api/v2/asset-backups' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer  <access-token> ' \
{
    "assetId": "96bf22bb-d02f-593c-a5a1-21093bc253f8",
    "backupType": "AUTO_FULL"
}'

The response of the API call is similar to:

403 (Forbidden)

{
    "code": 403,
    "reason": "User test does not have proper privileges!",
    "remediation": null,
    "timestamp": 1612424205753,
    "path": "/api/v2/asset-backups",
    "extendedInfo": null
}

To find the user privilege for different roles, use API GET /api/v2/roles:

curl --request GET 'https://<your-ppdm-server>:8443/api/v2/roles'
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer  <access-token> ' \

The response of the API call is similar to:

{
    "content": [
        {
            "id": "2bc90020-7675-0136-29e9-5bbd3ce729b0",
            "name": "Admin",
            "description": "Provides a user with system-wide access to all functionality across all organizations. This role is the default role. For example, assign this role to the user in your organization that requires full access control to the system.",
            "systemRole": true,
            "hiddenRole": false,
            "transferable": false,
            "privilegeList": [
                {
                    "name": "Monitor Events",
                    "description": "View events",
                    "category": "Monitoring"
                },
                ...
            ]
        },
        {
            "id": "2bc9eaa0-7675-0136-29e9-5bbd3ce729b0",
            "name": "Export and Recovery Admin",
            "description": "Provides an authorized user with access only to functionality required to manage data export and recovery operations.  This role and its operations are intended for a limited set of users whose actions are solely focused on data management, export, and recovery operations and routinely audited for security purposes.  For example, assign this role to the user in your organization that only requires access to data to make it available to other users in your organization to maintain a chain of custody record.",
            "systemRole": false,
            "hiddenRole": false,
            "transferable": false,
            "privilegeList": [
                {
                    "name": "Monitor Events",
                    "description": "View events",
                    "category": "Monitoring"
                },
                ...
            ]
        },
        ...
    ]
}

404 Not Found

This response means that the server has not found any resource matching the request operation. The error code indicates that the resource does not exist or, for security reasons, the service decides to mask a 401 or 403 error.

In PowerProtect Data Manager, the API GET /api/v2/assets/{assetId} retrieves the asset that is indicated by assetId. In this example, an incorrect asset ID is given:

curl --request GET \
--url 'https://<your-ppdm-server>:8443/api/v2/assets/test-wrong-asset-id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>'

The response of the API call is similar to:

404 (Not Found)

{
    "code": 404,
    "reason": "The requested resource /api/v2/assets/test-wrong-asset-id is not supported.",
    "remediation": "Check to ensure that the request URI and method are correct.",
    "timestamp": 1612366730351,
    "path": "/api/v2/assets/96bf22bb-d02f-593c-a5a1-21093bc253f8aa",
    "extendedInfo": null
}

To fix this error, use correct assetId:

curl --request GET \
--url 'https://<your-ppdm-server>:8443/api/v2/assets/96bf22bb-d02f-593c-a5a1-21093bc253f8' \
--header 'Authorization: Bearer <access-token>'

The response of the API call is similar to:

200 (OK)

{
    "id": "96bf22bb-d02f-593c-a5a1-21093bc253f8",
    "name": "(10.110.4.26) dellemc-ppdm-sw-19.7.0-1-20201101.095211-235",
    "type": "VMWARE_VIRTUAL_MACHINE",
    ...
}

405 Method Not Allowed

This status code indicates that the request method is known by the server but is not supported by the target resource.

In PowerProtect Data Manager, the API /api/v2/search-clusters/{id}/config only supports the PUT operation. If you use GET for this API, like this:

curl --request GET 'https://<your-ppdm-server>:8443/api/v2/search-clusters/<search-clusters-id>/config' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: text/plain' \
{
  "indexRetentionDays": 123
}

The response of the API call is similar to:

405 (Method Not Allowed)

{
    "reason": "GET is not supported for /api/v2/search-clusters/b13282f1-e1e2-486a-84ff-fdf0146b872e/config.",
    "remediation": "Check to ensure that the request URI and method are correct.",
    "code": 405,
    "path": "/api/v2/search-clusters/b13282f1-e1e2-486a-84ff-fdf0146b872e/config",
    "timestamp": 1612429092247
}

As indicated in the remediation message, check the request URL and method. The API reference content lists the supported operations.

409 Conflict

This response is sent when a request conflicts with the current state of the server or resource. For example, if a discovery request is already processing, requesting the same discovery operation returns a 409 status code.

In PowerProtect Data Manager, you can use the API POST /api/v2/inventory-sources to create an inventory source. In this case, a vCenter {vCenter-name} that has been added as an inventory source is used again in POST request, like this:

curl --request POST 'https://<your-ppdm-server>:8443/api/v2/inventory-sources' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token> \
'{
    "name": "{{vCenter-name}}",
    "type": "VCENTER",
    "address": "{{vCenter-ip}}",
    "port": 443,
    "credentials": {
        "id": "2e4445a7-bff9-432e-aa38-f5d877b2e79d"
    }
}'

The response of the API call is similar to:

409 (Conflict)

{
    "code": 409,
    "reason": "The specified vCenter with the address of <vCenter-name> conflicts with existing vCenter name <vCenter-name>.",
    "remediation": "Try again with a valid request.",
    "timestamp": 1612422866735,
    "path": "/api/v2/inventory-sources",
    "extendedInfo": null
}

422 Unprocessable Entity

The request was well-formed but was unable to complete because of semantic errors. This status code indicates that the server understands the entity content type, and the syntax is correct, but the server could not process the contained instructions.

For example, this error condition may occur when creating a user or changing a password, and the given password is not valid.

curl --request POST 'https://<your-ppdm-server>:8443/api/v2/users' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: text/plain' \
'{
  "emailAddress": "<email-address>",
  "firstName": "a",
  "forcePasswordChange": true,
  "lastName": "b",
  "password": "test",
  "roleId": "2bc98750-7675-0136-29e9-5bbd3ce729b0",
  "username": "user1"
}'

The response of the API call is similar to:

422 (Unprocessable Entity (WebDAV))

{
    "code": 422,
    "reason": "Password must have minimum 9 and maximum 100 characters, at least 1 uppercase letter, at least 1 lowercase letter, at least 1 numeric and at least 1 special character.",
    "remediation": "Fix the problem and try again"
}

Server error response

500 Internal Server Error

This status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

503 Service Unavailable

This status code indicates that the server is unable to handle the request because of a temporary overload or scheduled maintenance.

In PowerProtect Data Manager, each API call has a defined timeout. If you experience a timeout, try to reduce the number of resources being processed simultaneously, and verify the optimal number for your environment.