Responses

All responses to requests will be in JSON format, except when making a request with downloadFile. Any warning and error response objects will call out any problems with your request.

❗️

NOTE ON HTTP 200 response

An HTTP 200 response with a success=true does not indicate that an action was successful — you must verify there are no error or warning messages. A successful call will always result in a 200 status with success=true and no error.message or warning.message. We only indicate that the request was received, NOT to provide the API action was successful.

Types of responses

Success with warning responses: HTTP 200

Response 1: success=true (no warning or error objects) ;
The request was received and the action taken successfully.

{ 
  "response": [
    {
      "success": true
    }
  ]
}

Response 2: success=true and warning.message=“warning message" ;
The request was received successfully but the action was likely skipped. See warning message for details.

{ 
  "response": [
    {
      "success": true,
      "warning": {
        "message": "User not found; request skipped."
      }
    }
  ]
}

Response 3: success=true and error.message=“error message" ;
The request was received successfully but the action was skipped. See error message for details.

{
  "response": [
    {
      "success": true,
      "error": {
        "message": "Error message provided here."
      }
    }
  ]
}

Errors: HTTP 4xx, 5xx

Response 1: success=false and error.message=“error message" ; .
The request was not received successfully. See error messages below for details on each error and how to resolve.

Invalid access key - Provide the correct key to resolve.

{
  "response": [
    {
      "success": false,
      "error": {
        "message": "Invalid access key"
      }
    }
  ]
}

429 strict device locking or rate limit

Strict device locking - Strict device locking is caused by making multiple API calls with the same userId at the same time. We make sure no GET or POST requests can be executed at the same time to ensure consistent data.

DevMode Rate limit - For requests you include the parameter devMode=true, there is a maximum rate limit of 1 request per second. When this happens you will see the error message: "Per device rate limit exceeded." or "Too Many Requests."

When this happens we recommend retrying with an exponential backoff to resolve, up to a maximum amount of retries. For example, you could use exponential backoff starting with 5 seconds ranging up to a minute depending on your use case.

{
  "response": [
    {
      "success": false,
      "error": {
        "message":"Request failed due to concurrent requests to the same profile ID"
      }
    }
  ]
}

451 Unavailable For Legal Reasons.

This status code is returned when the API call is attempting to update a userId which has been blocked with the [block api call.] (ref:post_api-action-block)

5xx error

For any HTTP 5xx errors, we recommend retrying with exponential backoff to resolve, up to a maximum amount of retries. For example, you could use exponential backoff starting with 5 seconds ranging up to a minute depending on your use case.

Retrying

For any response where you receive an HTTP 5xx (internal server) error or a 429, you should first retry the request. Using an exponential backoff strategy in this case, up to a maximum amount of retries, is our recommendation.
If you are looking for where to start, see the example below:

1. retry after 2 +/- random(0, 1) seconds, then
2. retry after 4 +/- random(0, 2) seconds, then
3. retry after 8 +/- random(0, 4) seconds
4. etc.