Developer Documentation
Global App Configuration Service

Troubleshooting the Global Apps Configuration Service APIs

July 31, 2023
Contributed by: 
C

This document describes the error codes and responses that Global Apps Configuration Service APIs return. The response codes for the following APIs are covered in this document:

An unsuccessful Global App Configuration service API request returns the following error information in the response body:

  • type - A standard HTTP response code. For example, HTTP Status Code 404: Entity not found.
  • details - A brief description of the error.
  • parameters - An optional JSON object to provide additional information about the error.

Following is a sample API error response code:

{
    "type": "HTTP Status Code 404: Entity not found",
    "detail": "resource not found",
    "parameters": {
        "name": "entityType",
        "value": "the request URL"
    }
}
<!--NeedCopy-->

Discovery APIs

APIs Description
GET /discovery The GET request is called to fetch the result of all the discovery records for a specific customer. After the customer creates a discovery record based on the app (Product) and domain, the result is displayed. The GET request also helps in determining if the customer has claimed and created a discovery record based on a domain. This request returns an HTTP 200 response with a collection of discovery records for the requested customer.
POST /discovery/app/{app}/domain The POST request is placed only once for a combination of app and domain. In case the request is already placed the error is as per HTTP 409 response code. The body parameters for both PUT and POST are the same and are explained in the following sections.
GET /discovery/app/{app}/domain/{domain} The GET operation for a particular discovery record is based on the app and domain name. This request returns an HTTP 200 response with a single discovery record in a collection.
PUT /discovery/app/{app}/domain/{domain} The PUT request is used to update a discovery record with the combination of app and domain. The body parameters for both PUT and POST are the same and are explained in the following sections. This request returns an HTTP 204 No Content response on a successful update.
DELETE /discovery/app/{app}/domain/{domain} The DELETE request is used to delete a discovery record with the combination of app and domain. This request returns an HTTP 204 No Content response on a successful delete.

Sample Request 

 {
  "domain": {
    "name": "aca.example.com"
  },
  "app": {
    "workspace": {
      "serviceURLs": [
        {
          "url": "https://nsg.example.com:443"
        },
        {
          "url": "https://store.example.com:443/Citrix/Store"
        }
      ]
    }
  }
}
<!--NeedCopy-->

POST and PUT body parameters

Parameters Description
domain The values are case sensitive.
app enum value allowed is “workspace”. The values are case sensitive.
serviceURLs enum value allowed is “url”. The values are case sensitive.
url The values are case sensitive. The values require the protocol “https” or “HTTP” and port number.

POST, PUT, GET, and DELETE path parameters

Parameters Description
app enum values allowed “workspace”. The values aren’t case sensitive.
domain PUT GET DELETE only The values are case sensitive.

Response codes for Discovery APIs

The following table lists the response codes and their description for the Discovery APIs.

HTTP status code API Description
200 OK    
  GET /discovery The status code indicates that the request has succeeded. For more information, see use cases.
201 Created    
  POST /discovery/app/{app}/domain The status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. For more information, see use cases.
204 No Content    
  PUT /discovery/app/{app}/domain{domain} Records are updated or deleted successfully. The status code indicates that the server has successfully fulfilled the request and there’s no additional content to send in the response body.
400 Validation Errors    
  POST /discovery/app/{app}/domain The status code indicates that the server cannot process the request because of a perceived client error. For more information, see use cases.
  PUT /discovery/app/{app}/domain/{domain}  
401 Unauthorized    
  GET /discovery The status code indicates that the request isn’t applied because it lacks valid authentication credentials for the target resource. For more information, see use cases.
  POST /discovery/app/{app}/domain/  
  GET /discovery/app/{app}/domain/{domain}  
  PUT /discovery/app/{app}/domain/{domain}  
  DELETE /discovery/app/{app}/domain/{domain}  
403 Forbidden    
  GET /discovery The status code indicates that the server understood the request but refuses to authorize the request. For more information, see use cases.
  POST /discovery/app/{app}/domain/  
  GET /discovery/app/{app}/domain/{domain}  
  PUT /discovery/app/{app}/domain/{domain}  
  DELETE /discovery/app/{app}/domain/{domain}  
404 Not Found    
  GET /discovery The status code indicates that the origin server didn’t find a current representation for the target resource or isn’t willing to reveal that one that exists. For more information, see use cases.
  GET /discovery/app/{app}/domain/{domain}  
  PUT /discovery/app/{app}/domain/{domain}  
  DELETE /discovery/app/{app}/domain/{domain}  
409 Conflict    
  POST /discovery/app/{app}/domain/ The status code indicates that the request can’t complete because of a conflict with the current state of the target resource. For more information, see use cases.
503 Service Unavailable    
  GET /discovery The status code indicates that the server is unable to handle the request because of a temporary overload or scheduled maintenance, and likely to alleviate after some delay. For more information, see use cases. Note: Report these errors directly to the engineering team to help resolve the issues. Take a note of the customer ID and transaction ID from the customer to troubleshoot further.
  GET /discovery/app/{app}/domain/{domain}  
  POST /discovery/app/{app}/domain/  
  PUT /discovery/app/{app}/domain/{domain}  

HTTP status code: 200 OK

Case 1: When the customers have saved a single record

[
  {
    "domain": {
      "name": "aca.example.com"
    },
    "app": {
      "workspace": {
        "serviceURLs": [
          {
            "url": "https://nsg.example.com:443"
          },
          {
            "url": "https://store.example.com:443/Citrix/Store"
          }
        ]
      }
    }
  }
]
<!--NeedCopy-->

Case 2: When the customers have saved multiple records

[
  {
    "domain": {
      "name": "aca.example.com"
    },
    "app": {
      "workspace": {
        "serviceURLs": [
          {
            "url": "https://nsg.example.com:443"
          },
          {
            "url": "https://store.example.com:443/Citrix/Store"
          }
        ]
      }
    }
  },
  {
    "domain": {
      "name": "aca.example1.com"
    },
    "app": {
      "workspace": {
        "serviceURLs": [
          {
            "url": "https://nsg.example.com:443"
          },
          {
            "url": "https://store.example.com:443/Citrix/Store"
          }
        ]
      }
    }
  }
]
<!--NeedCopy-->

HTTP status code: 201 Created

Case 1: When the request is successful

  {
    "domain": {
      "name": "aca.example1.com"
    },
    "app": {
      "workspace": {
        "serviceURLs": [
          {
            "url": "https://nsg.example.com:443"
          },
          {
            "url": "https://store.example.com:443/Citrix/Store"
          }
        ]
      }
    }
  }
<!--NeedCopy-->

HTTP status code: 400 Validation error

Case 1: If the fields are empty the error shows the mandatory fields to be filled

{
  "detail": "App name is null or Invalid",
  "type": "HTTP Status Code 400: Bad Request",
  "parameters": [
    {
      "name": "appName",
      "value": "{app}"
    },
    {
      "name": "domainName",
      "value": "{yourDomainName}"
    },
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

Case 2: When the app or product is invalid

{
  "detail": "App name is null or Invalid",
  "type": "HTTP Status Code 400: Bad Request",
  "parameters": [
    {
      "name": "app",
      "value": "{app}"
    },
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

Case 3: When a domain is invalid

{
  "detail": "Discovery handle not verified by Domain Claim",
  "type": "HTTP Status Code 400: Bad Request",
  "parameters": [
    {
      "name": "appName",
      "value": "workspace"
    },
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

HTTP status code: 401 Unauthorized

Case 1: If the Authorization header is empty or missing, the reason is mentioned in the parameters value as missing

{
    "detail": "Unauthorized HTTP request",
    "type": "HTTP Status Code 401: Unauthorized",
    "parameters": [
        {
            "name": "Reason",
            "value": "Missing"
        }
    ]
}
<!--NeedCopy-->

Case 2: If the Authorization header is invalid, the reason is mentioned in the parameters value as invalid

{
  "detail": "Unauthorized HTTP request",
  "type": "HTTP Status Code 401: Unauthorized",
  "parameters": [
    {
      "name": "Reason",
      "value": "Invalid"
    }
  ]
}
<!--NeedCopy-->

HTTP status code: 403 Forbidden

Case 1: Customer isn’t entitled to use the service

{
  "detail": "Access denied",
  "type": "HTTP Status Code 403: Forbidden",
  "parameters": [
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

HTTP status code: 404 Not Found

Case 1: The requested record wasn’t found

{
  "detail": "Resource not found",
  "type": "HTTP Status Code 404: Entity not found",
  "parameters": [
    {
      "name": "app",
      "value": "{app}"
    },
    {
      "name": "domain",
      "value": "{yourDomain}"
    },
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

HTTP status code: 409 Conflict 

{
  "detail": "Resource already exist for domain name",
  "type": "HTTP Status Code: 409: Conflict",
  "parameters": [
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

HTTP status code: 503 Service Unavailable

Case 1: Internal Server Errors

{
    "detail": "Service unavailable",
    "type": "HTTP Status Code 503: Service Unavailable",
    "parameters": [
        {
            "name": "ccCustomerId",
            "value": "{yourCustomerId}"
        },
        {
            "name": "app",
            "value": "{app}"
        },
        {
            "name": "domain",
            "value": "{domain}"
        }
    ]
}
<!--NeedCopy-->

Settings APIs

APIs Description
GET /settings The GET request is called to fetch the result of all the settings records for a specific customer. After the customer creates a setting record based on the app (Product) and service URL, the result is displayed. The GET request also helps in determining if a domain has been claimed and created a setting record based on a domain. This request returns an HTTP 200 response with a collection of settings records.
POST /settings/app/{app}/url The POST request is placed only once for a combination of app and url. In case the request is already placed and if a record for app and url combination exists the HTTP 409 response code is returned. The body parameters for both PUT and POST are the same and are explained in the following sections.
GET /settings/app/{app}/url/{url} This request returns an HTTP 200 response with a settings record for an app and url.
PUT /settings/app/{app}/url/{url} The PUT request is used to update a settings record for a combination of app and url. The body parameters for both PUT and POST are the same and are explained in the following sections. This request returns an HTTP 204 No Content response on a successful update.
DELETE /settings/app/{app}/url/{url} The DELETE request is used to delete a settings record for a combination of app and url. This request returns an HTTP 204 No Content response on a successful delete.

Sample request 

  {
    "serviceURL": {
      "url": "https://sampleworkspace.cloud.com:443"
    },
    "settings": {
      "name": "Productivity Apps",
      "description": "Provides access to MS Office Apps",
      "useForAppConfig": true,
      "appSettings": {
        "ios": [
          {
            "category": "Audio",
            "userOverride": false,
            "assignedTo": [
              "AllUsersNoAuthentication"
            ],
            "assignmentPriority": 0,
            "settings": [
              {
                "name": "audio",
                "value": "true"
              }
            ]
          },
          {
            "category": "Display",
            "userOverride": false,
            "assignedTo": [
              "AllUsersNoAuthentication"
            ],
            "assignmentPriority": 0,
            "settings": [
              {
                "name": "Session Resolution",
                "value": "Autofit High Resolution"
              }
            ]
          }
        ],
        "android": [
          {
            "category": "Audio",
            "userOverride": true,
            "assignedTo": [
              "AllUsersNoAuthentication"
            ],
            "assignmentPriority": 0,
            "settings": [
              {
                "name": "Audio Streaming",
                "value": "Play and record"
              }
            ]
          }
        ],
        "windows": [
          {
            "category": "Keyboard",
            "userOverride": false,
            "assignedTo": [
              "AllUsersNoAuthentication"
            ],
            "assignmentPriority": 0,
            "settings": [
              {
                "name": "Use Predictive Text",
                "value": "false"
              }
            ]
          }
        ]
      }
    }
  }
<!--NeedCopy-->

POST and PUT body parameters

Parameter Description
serviceURL The allowed values are URL objects.
url Values are case sensitive. The values require the protocol “https” or “HTTP” and port number.
settings Values are case sensitive. For Settings Object, see settings matrix in the Getting Started page.

POST, PUT, GET, DELETE path parameters

Parameter Description
app Values are NOT case sensitive. Only valid value is “workspace”
url PUT GET DELETE Values are NOT case sensitive. Encode the value using a base 64 URL.

Response codes for the Settings APIs

The following table displays the response codes and their description for the Settings APIs.

HTTP status code API Description
200 OK    
  GET /settings The status code indicates that the request has succeeded. For more information, see use cases.
201 Created    
  POST /settings/app/{app}/url/ The status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. For more information, see use cases.
204 No Content    
  PUT /settings/app/{app}/url/{url} No Response Record were updated or deleted successfully. The status code indicates that the server has successfully fulfilled the request and that there is no additional content to send in the response body.
  DELETE /settings/app/{app}/url/{url} No Response  
400 Validation Errors    
  POST /settings/app/{app}/url/ The status code indicates that the server can’t or will not process the request because of perceived client error. For more information, see use cases.
  PUT /settings/app/{app}/url/{url}  
401 Unauthorized    
  GET /settings The status code indicates that the request isn’t applied because it lacks valid authentication credentials for the target resource. For more information, see use cases.
  POST /settings/app/{app}/url/  
  GET /settings/app/{app}/url/{url}  
  PUT /settings/app/{app}/url/{url}  
  DELETE /settings/app/{app}/url/{url}  
403 Forbidden    
  GET /settings The status code indicates that the server understood the request but refuses to authorize the request. For more information, see use cases.
  POST /settings/app/{app}/url/  
  GET /settings/app/{app}/url/{url}  
  PUT /settings/app/{app}/url/{url}  
  DELETE /settings/app/{app}/url/{url}  
404 Not Found    
  GET /settings The status code indicates that the origin server didn’t find a current representation for the target resource or isn’t willing to reveal that one exists. For more information, see use cases.
  GET /settings/app/{app}/url/{url}  
  PUT /settings/app/{app}/url/{url}  
  DELETE /settings/app/{app}/url/{url}  
409 Conflict    
  POST /settings/app/{app}/url/ The status code indicates that the request can’t complete due to a conflict with the current state of the target resource. For more information, see use cases.
503 Service Unavailable    
  GET /settings The status code indicates that the server is unable to handle the request because of a temporary overload or scheduled maintenance, which will likely alleviate after some delay. For more information, see use cases. Note: Report these errors directly to the engineering team to help resolve the issues. Take a note of the customer ID and Transaction ID from the customer to troubleshoot further.
  POST /settings/app/{app}/url/  
  GET /settings/app/{app}/url/{url}  
  PUT /settings/app/{app}/url/{url}  

HTTP status code: 200 OK

Case 1: When a single record has been created

  {
    "serviceURL": {
      "url": "https://sampleworkspace.cloud.com:443"
    },
    "settings": {
      "name": "Productivity Apps",
      "description": "Provides access to MS Office Apps",
      "useForAppConfig": true,
      "appSettings": {
        "ios": [
          ....
        ],
        "android": [
          ....
        ],
        "windows": [
          ....
        ]
      }
    }
  }
<!--NeedCopy-->

Case 2: When multiple records are created

[
  {
    "serviceURL": {
      "url": "https://[yourWorkspaceSite]:443"
    },
    "settings": {
      "name": "Productivity Apps",
      "description": "Provides access to MS Office Apps",
      "useForAppConfig": true,
      "appSettings": {
        "ios": [
          ....
        ],
        "android": [
          ....
        ],
        "windows": [
          ....
        ]
      }
    }
  },
  {
    "serviceURL": {
      "url": "https://sampleworkspace.cloud.com:443"
    },
    "settings": {
      "name": "Productivity Apps",
      "description": "Provides access to MS Office Apps",
      "useForAppConfig": true,
      "appSettings": {
        "ios": [
          ....
        ],
        "android": [
          ....
        ],
        "windows": [
          ....
        ]
      }
    }
  }
]
<!--NeedCopy-->

HTTP status code: 201 Created

Case 1: When a request is successful

  {
    "serviceURL": {
      "url": "https://sampleworkspace.cloud.com:443"
    },
    "settings": {
      "name": "Productivity Apps",
      "description": "Provides access to MS Office Apps",
      "useForAppConfig": true,
      "appSettings": {
        "ios": [
          ....
        ],
        "android": [
          ....
        ],
        "windows": [
          ....
        ]
      }
    }
  }
<!--NeedCopy-->

HTTP status code: 400 Validation Errors

Case 1: If the fields are empty the error shows the mandatory fields to be filled

{
  "detail": "App name is null or Invalid",
  "type": "HTTP Status Code 400: Bad Request",
  "parameters": [
    {
      "name": "app",
      "value": "{app}"
    },
    ...
    {
      "name": "url",
      "value": "{url}"
    },
    ...
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

Case 2: When the app or product is invalid

{
  "detail": "App name is null or Invalid",
  "type": "HTTP Status Code 400: Bad Request",
  "parameters": [
    {
      "name": "app",
      "value": "{app}"
    },
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

Case 3: When service URL is invalid

{
  "detail": "Input byte array has wrong x-byte ending unit",
  "type": "HTTP Status Code 400: Bad Request",
  "parameters": [
    {
      "name": "url",
      "value": "{url}"
    },
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

Case 4: When service URL isn’t base 64 URL encoded

{
  "detail": "Illegal base64 character 2e",
  "type": "HTTP Status Code 400: Bad Request",
  "parameters": [
    {
      "name": "url",
      "value": "{url}"
    },
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

HTTP status code: 401 Unauthorized

Case 1: If the Authorization header is empty or the parameter value is missing

{
    "detail": "Unauthorized HTTP request",
    "type": "HTTP Status Code 401: Unauthorized",
    "parameters": [
        {
            "name": "Reason",
            "value": "Missing"
        }
    ]
}
<!--NeedCopy-->

Case 2: If the Authorization header is invalid, the parameters value is invalid

{
  "detail": "Unauthorized HTTP request",
  "type": "HTTP Status Code 401: Unauthorized",
  "parameters": [
    {
      "name": "Reason",
      "value": "Invalid"
    }
  ]
}
<!--NeedCopy-->

HTTP status code: 403 Forbidden

Case 1: The customer isn’t entitled to use the service

{
  "detail": "Access denied",
  "type": "HTTP Status Code 403: Forbidden",
  "parameters": [
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

HTTP status code: 404 Not Found

Case 1: The requested record wasn’t found

{
  "detail": "Resource not found",
  "type": "HTTP Status Code 404: Entity not found",
  "parameters": [
    {
      "name": "app",
      "value": "{app}"
    },
    {
      "name": "url",
      "value": "{url}"
    },
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

HTTP status code: 409 Conflict 

{
  "detail": "Resource already exist for service url",
  "type": "HTTP Status Code: 409: Conflict",
  "parameters": [
    {
      "name": "ccCustomerId",
      "value": "{yourCustomerId}"
    }
  ]
}
<!--NeedCopy-->

HTTP status code: 503 Service Unavailable

Case 1: Internal Server Errors

{
    "detail": "Service unavailable",
    "type": "HTTP Status Code 503: Service Unavailable",
    "parameters": [
        {
            "name": "ccCustomerId",
            "value": "{yourCustomerId}"
        },
        {
            "name": "app",
            "value": "{app}"
        },
        {
            "name": "url",
            "value": "{url}"
        }
    ]
}
<!--NeedCopy-->
Resources
Global App Configuration Service OpenAPI Specification
Copy Download
Troubleshooting the Global Apps Configuration Service APIs
July 31, 2023
Contributed by: 
C
July 31, 2023
Contributed by: 
C

In this article

Resources
Global App Configuration Service OpenAPI Specification
Copy Download
Site feedback | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.