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

400 - Bad Request

The caller passed data that does not meet all validation rules, or is invalid based on the application state.

  • Some common  types for errors are:
    • https://errors-api.cloud.com/common/outOfRange: a number is out of range. 
    • https://errors-api.cloud.com/common/tooLong: a string is too long.
    • https://errors-api.cloud.com/common/invalidString: a string was specified with invalid characters (does not match the validation regex).
    • https://errors-api.cloud.com/common/invalidEnum: a value was specified for an enumeration property which the service did not understand.
    • https://errors-api.cloud.com/common/missing: a required input value was missing.
    • https://errors-api.cloud.com/common/invalidJson: The input json uses non-standard json extensions or is simply not well formed json.
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"
        }
    ]
}
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"
        }
    ]
}
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"
        }
    ]
}
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"
        }
    ]
}
409 - Request Conflict

The caller attempted to make a change providing an 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"
}
415 - Unsupported Media Type

The caller is being rate-limited. 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"
        }
    ]
}
429 - Too Many Requests

The caller is being rate-limited. 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"
        }
    ]
}
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"
}
503 - Service Unavailable

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

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