Common Citrix Cloud API error codes

Each API defines success and failure codes independently but a few response codes are common across Citrix Cloud.

This section gives a list of common error code responses that the REST API generates.

400-Bad Request

The caller passed data that does not meet all validation rules, or is invalid based on the application state. Following table lists the common error types and description:

401-Unauthorized

Caller passed invalid authentication data (no authentication, or a bad bearer token).

Example response body:

{
    "type": "https://errors-api.cloud.com/common/authentication",
    "detail": "Missing or invalid authentication details",
    "parameters": [
        {
            "name": "reason",
            "value": "missing"
        }
    ]
}
<!--NeedCopy-->

403-Forbidden

Caller passed valid authentication data, but does not have adequate permissions to call the requested API.

Example response body:

{
    "type": "https://errors-api.cloud.com/common/authorization",
    "detail": "Access denied",
    "parameters": [
        {
            "name": "entityType",
            "value": "https://identifiers-api.cloud.com/example/widget"
        },
        {
            "name": "id",
            "value": "guid1"
        }
    ]
}
<!--NeedCopy-->

User is not authenticated for the specified resource

Some services are geo-dependent. If you are calling a service that is geo-dependent and you are using a geographical region other than the one selected when creating the Citrix Cloud account, the following error might occur:

{
  "type": "https://errors-api.cloud.com/common/authorization",
  "detail": "Access denied",
  "parameters": [
    {
      "name": "message",
      "value": "User is not authenticated for the specified resource"
    },
    {
      "name": "entityType",
      "value": "https://catalogs.apps.cloud.com/customer"
    },
    {
      "name": "id",
      "value": "XXXXXXXXXXXX"
    }
  ]
}
<!--NeedCopy-->

Solution:

When you register an API client, authenticate an API request, or invoke an API request, you must use one of the following endpoint prefixes:

• api-ap-s.cloud.com – If your Citrix Cloud account is set to the Asia Pacific South region.
• api-eu.cloud.com – If your Citrix Cloud account is set to the European Union region.
• api-us.cloud.com – If your Citrix Cloud account is set to the United States region.
• api.citrixcloud.jp - If your Citrix Cloud account is set to the Japan region.

404-Not Found

Entity not found. Response must indicate the type of entity not found, and the ID by which the entity was attempted to be located.

Example response body:

{
    "type": "https://errors-api.cloud.com/common/notFound",
    "detail": "Widget not found",
    "parameters": [
        {
            "name": "entityType",
            "value": "https://identifiers-api.cloud.com/example/widget"
        },
        {
            "name": "id",
            "value": "guid1"
        }
    ]
}
<!--NeedCopy-->

406-Not Acceptable

Indicates that the caller passed a value in the Accept header which indicates an unsupported media type. It is preferable to be restrictive rather than flexible. Do not support media types if you don’t have to.

Example response body:

{
    "type": "https://errors-api.cloud.com/common/notAcceptable",
    "detail": "Must accept application/json media type",
    "parameters": [
        {
            "name": "contentType",
            "value": "application/json"
        }
    ]
}
<!--NeedCopy-->

409-Request Conflict

The caller attempted to make a change providing an Entity tag (ETag) but the ETag did not match the current state of the entity (optimistic concurrency failure).

Example response body:

{
    "type": "https://errors-api.cloud.com/common/optimisticConcurrency",
    "detail": "Widget X was modified, please try your changes again"
}
<!--NeedCopy-->

415-Unsupported Media Type

The service cannot accept the request because the payload format is not supported.

Example response body:

{
    "type": "https://errors-api.cloud.com/common/unsupportedMediaType",
    "detail": "Must use application/json; charset=utf-8 media type",
    "parameters": [
        {
            "name": "mediaType",
            "value": "application/xml"
        }
    ]
}
<!--NeedCopy-->

429-Too Many Requests

The caller is being rate-limited. Services set their own rate limits. Refer to the Rate Limit section of the service for more details.

Example response body:

{
    "type": "https://errors-api.cloud.com/common/rateLimitExceeded",
    "detail": "Rate limit exceeded; try again in 4 seconds",
    "parameters": [
        {
            "name": "retryDelay",
            "value": "4"
        }
    ]
}
<!--NeedCopy-->

501-Not Implemented

API is not yet implemented but might be implemented at some point in the future.

Example response body:

{
    "type": "https://errors-api.cloud.com/common/notImplemented",
    "detail": "Not implemented"
}
<!--NeedCopy-->

503-Service Unavailable

Service is unavailable through no fault of the caller. A caller can retry at some point in the future.

Example response body:

{
    "type": "https://errors-api.cloud.com/common/serviceUnavailable",
    "detail": "Service is unavailable; try again in 4 seconds",
    "parameters": [
        {
            "name": "retryDelay",
            "value": "4"
        }
    ]
}
<!--NeedCopy-->