Typical Response Structure

Successful responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object(s) requested, created, modified, or deleted along with an expression of the server’s interpretation of your request.

If you had issued a successful request you would receive as part of your response a request node echoing back your request.

Example: GET accounts/abcdefg/campaigns?with_deleted=true

{
  /* the data of your response... */,
  "request": {
    "params": {
      "account_id": "abcdefg",
      "with_deleted": "true"
    }
  }
}

The data field in JSON responses will contain the specific objects associated with the leveraged resource. The format of the data node will be a JSON array when the response may contain one or more results. It will be returned as JSON hash when only one result is possible in response. In some rare cases, you may see a response that would typically include a collection with a hashmap instead. In this case, assume the single hashmap is an object of the same type as specified in the type field.

Error Response Structure

Error responses are served with a non-200-series HTTP code. Usually a JSON response will be attached, but some errors will respond with different kinds of body. In these circumstances where a response structure cannot be parsed, consider the HTTP code’s core meaning to take precedence. For instance, you may occasionally see a HTTP 404 along with a HTML response. In this case, it’s safe to assume that the content cannot be found (HTTP 404 means “Not Found”).

Typical error responses follow a similar structure to successful responses. The nature of the error will be communicated in an errors node of the response. The errors/code node will indicate a CAPS_CASE constant error code you can programmatically consume to make resolution decisions from. The errors/message node will indicate a (usually) human-readable description of the error in English. Additional fields may be attached to indicate finer-grained detail about the error.

{
  "errors": [
    {
      "parameter": "start_time",
      "details": "invalid date",
      "code": "INVALID_PARAMETER",
      "value": "",
      "message": "Expected time, got \"\" for start_time"
    }
  ],
  "request": {
    "params": {
      "account_id": "hkk5"
    }
  }
}

In the above example, a request to an analytics endpoint was made with an invalid value for the start_time parameter. The errors/code for requests with invalid parameters is INVALID_PARAMETER.