API Errors

The Cisco Spark API returns standard HTTP status codes for request responses. If an error occurs, more information will be provided in the response.

HTTP Response Codes

The list below describes the common success and error responses you should expect from the API.

Code Status Description
200 OK Successful request with body content.
204 No Content Successful request without body content.
400 Bad Request The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized Authentication credentials were missing or incorrect.
403 Forbidden The request is understood, but it has been refused or access is not allowed.
404 Not Found The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.
405 Method Not Allowed The request was made to a resource using an HTTP request method that is not supported.
409 Conflict The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.
429 Too Many Requests Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.
500 Internal Server Error Something went wrong on the server. If the issue persists, feel free to contact the Spark DevSupport team.
502 Bad Gateway The server received an invalid response from an upstream server while processing the request. Try again later.
503 Service Unavailable Server is overloaded with requests. Try again later.

Responses with Errors

When retrieving multiple resources from the API, such as listing multiple Rooms or People, individual resources which should be included in the response may not be included because of an error. If any partial failures occur, the API will respond with a 200 OK and the response body will contain the entire list of resources, including the individual resources which could not be retrieved.

Resources which encounter errors during retrieval will include an errors object. This errors object will contain a specific error code and reason describing why the individual resource could not be returned in the request. Failures encountered during the request may be the result of a temporary issue, such as the inability to contact an on-premise key management server in a timely manner, or something more permanent. The error code and description will provide more detail about the error.

The errors object should only be present in the response if at least one resource could not be retrieved.

Example Response with Errors

The sample JSON below demonstrates how an error encountered while retrieving one room in a list of rooms is presented:

  "items": [
      "id": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "title" : "Project Unicorn - Sprint 0",
      "type" : "group",
      "isLocked" : true,
      "teamId" : "Y2lzY29zcGFyazovL3VzL1JPT00vNjRlNDVhZTAtYzQ2Yi0xMWU1LTlkZjktMGQ0MWUzNDIxOTcz",
      "lastActivity" : "2016-04-21T19:12:48.920Z",
      "created" : "2016-04-21T19:01:55.966Z"
      "id": "Y2lzY29zcGFyazovL3VzL1JPT00vNTIxN0EyMzYtNDQzQi00NThELTkzNjAtRDRFOTMyMTBBNUU5",
      "errors": {
        "title": {
          "code": "kms_failure",
          "reason": "Key management server failed to respond appropriately. For more information: https://developer.ciscospark.com/errors.html"

Error Codes

The following table describes the errors which may be returned by the API:

Code Reason Description
kms_failure Key management server failed to respond appropriately. The Spark API is unable to contact the appropriate encryption key management server (KMS), or the KMS did not respond in a timely manner, and could not retrieve the requested resource. Try your request again later.

SSL Connection Errors

The Cisco Spark API uses the Server Name Indication (SNI) extension to TLS/SSL. If your SSL client fails to connect to the API with an error such as hostname 'api.ciscospark.com' doesn't match either of '*.wbx2.com', 'wbx2.com', your client may not support SNI. Verify that your client supports the SNI extension. If your client does not support the SNI extension, then upgrade your client to a version which will support it and try your request again. Never configure your client to ignore SSL connection errors.

SNI support was implemented in these versions of the following common libraries and tools:

  • Java 1.7
  • PHP 5.3
  • Python 2.7.9, Python 3
  • Ruby (net/http) 2.0
  • cURL 7.18.1
  • wget 1.14