Error Handling

Error handling is part of using the REST APIs in PubSub+ Cloud.

Whenever you use REST APIs for PubSub+ Cloud, a response is returned to indicate success or errors using standard 2xx, 4xx, and 5xx HTTP response codes as documented for each REST endpoint but we have provided a summary for your convenience of all the possible codes. Specific error information is available in the response when an error occurs.

HTTP Response Codes

The REST API uses the following common, response codes. For errors, the response includes an error object that gives you more details about the error.

CodeMeaning
200OK. The request was successful and immediately completed.
201Created. The asynchronous request to create an object was successful and the object was created.
202Accepted. The request is an asynchronous operation that takes more than two seconds. The response contains a location header.
204No content. The request was successfully completed and no content was returned.
400Bad request. See the error code to determine the reason for the failure.
401Unauthorized. See the error code to determine the reason for the failure.
403Forbidden. See the error code to determine the reason for the failure.
404Not found. See the error code to determine the reason for the failure.
405Method not allowed. See the error code to determine the reason for the failure.
409Conflict. The operation conflicts with another operation in progress, could not be queued, or could not run in parallel with the other operation. See the error code to determine the reason.
Any 5xx errorFailed. An issue occurred in PubSub+ Cloud. See the error code to determine the reason for the problem.

Error Codes

You can use the message, errorId, and validationDetails keys to get more information on what occurred incorrectly. The string value in the message key may have more information as to why the error occurred.

The following response shows the JSON object that is returned as part of the40x or 50x HTTP response.

{
  message: "Unable to create messaging service US-EAST-Prod-1",
  errorId: "b05e5062-80c6-45f5-9b0c-c2f69bb7114a",
  validationDetails: {
    "name": [
      "Name must be unique"
    ],
    "dmrLink[2]": [
      "Hostname must be provided"
    ]
  }
}

Asynchronous Operations

For long-running operations (any operation that takes longer than two seconds), a response is returned so that your application doesn't need to wait for completion.

{
  "id": "string", 
  "resourceId": "string",
  "operationType": "string",
  "createdBy": "string", 
  "createdTime": "string",
  "completedTime": "string",
  "status": "string",
  "error" : {
    "message": "string",
    "errorId": "string"
}

Where:

  • id—The identifier of the operation that you can use to retrieve information about the asynchronous operation. This identifier is guaranteed to be unique for a given entity and can be in REST API to get information regarding the progress of the long-running operation.
  • resourceId—The identifier of the resource being operated on.
  • operationType—The description of the operation against the resource, such as create, failover, or import.
  • createdBy—The identifier for the user that initialized the operation.
  • createdTime—The ISO 8601-formatted date of the creation time for the operation.
  • completedTime—The ISO 8601-formatted date of the completion time of the operation whether it was successful or failed.
  • status—The status of the long-running operation. The states are:
    • pending—the operation is waiting to be executed and processing has not started
    • inProgress—the operation has started processing
    • succeeded—the operation has been completed successfully
    • failed—the operation failed and the error object provides details of the reason

Some REST API operations may have additional, custom states. If an error occurs (a 40x or 50x HTTP response), the following error object is returned in the response:

  • error—A non-null value when the status is failed, otherwise null. When non-null, the following keys are included:
    • message—A user-friendly message describing the reason for the error or what went wrong.
    • errorId—A universally unique identifier (UUID) is useful for debugging. You can provide this code as part of the information you send to our support team.