Standard Response Format

Success without resource creation
Success with resource creation
Accepted for future processing
Success with data version
Failure response
Error and warning information
Failure due to SparkQL _filter errors

Success without resource creation

The HTTP response status code is in the range of 200-299.

{
    "D": {
        "Success": true
    }
}

Success with resource creation

The HTTP response status code is in the range of 200-299. ResourceUri indicates the path to the newly-created resource.

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/servicename/XXXXX"
            }
        ]
    }
}

Accepted for future processing

The HTTP response status code is always 202 (Accepted). When API resources reply with a 202: Accepted, the requested data creation or update is scheduled for future processing.

{
    "D": {
        "Success": true
    }
}

Success with data version

The HTTP response status code is in the range of 200-299. For resources that support it, the Version attribute can used in the versions subresource to return the data to a previous state state. Note that many resources have an expiration after which the version cannot be restored. When deleting data, the version returned points to the data at a state just before deletion, and can be used to restore the data from deletion.

{
    "D": {
        "Success": true,
        "Version": 1
    }
}

Failure response

The HTTP response status code is not in the range of 200-299. Available Code and Message values are documented on the Spark API error code page. Codes are provided so API clients may handle errors more easily than by parsing a message.

{
    "D": {
        "Success": false,
        "Code": 1234,
        "Message": "Spark API message describing the problem"
    }
}

Error and warning information

Some services support an additional Errors attribute that further elaborate on why a request was unsuccessful, or to provide warnings about a successful response.

{
    "D": {
        "Success": false,
        "Code": 1234,
        "Message": "Spark API message describing the problem",
        "Errors": [
          {
            "Type": "InvalidRecord",
            "Record": {
                /* Record POST or PUT to the API */
            },
            "Errors": [
                {
                    "Type": "InvalidAttribute",
                    "Attribute": "DisplayName",
                    "Message": "The combination of DisplayName and PrimaryEmail must be unique"
                },
                {
                    "Type": "InvalidAttribute",
                    "Attribute": "Pets",
                    "Message": "Cannot be null"
                },
                {
                    "Type": "RuleViolation",
                    "Message": null,
                    "Rule": {
                        "Id": 1,
                        "Status": "Fatal",
                        "ResourceUri": "/vX/listings/rules/1",
                        "Group": null,
                        "Domain": null,
                        "Field": "BathsTotal",
                        "Action": "SET_REQUIRED",
                        "Expression": null
                    }
                }
            ]
          }
        ]
    }
}

Field	Supported Types	Description
`Type`	All	The error type.
`Message`	All	An additional developer-friendly message sometimes provided along with the error data.
`Attribute`	`InvalidAttribute`	The invalid attribute present (or missing) from the `POST` or `PUT` data.
`Errors`	`InvalidRecord`	A list of `InvalidAttribute` errors for the `Record`.
`Record`	`InvalidRecord`	The `POST` or `PUT` data that failed validation.
`Rules`	`RuleViolation`	A list of rules, such as listing rules, that were violated by the `POST` or `PUT` data.

Error Type	Description
`InvalidAttribute`	An attribute did not pass validation when creating or updating data.
`InvalidRecord`	The data provided when updating or creating a record did not pass validation. This type of error includes an `Errors` attribute with a list of `InvalidAttribute` errors.
`RuleViolation`	The data provided when updating or creating a record did not pass rules for that data type. This type of error includes a `Rules` attribute for resource-specific rules, such as Listing Rules.

Failure due to SparkQL _filter errors

When a request fails due to an invalid _filter parameter or a field is dropped, the additional attribute SparkQLErrors will be present to provided additional detail about the filter problem.

{
    "D": {
        "Message": "The SavedSearch you specified is not available.",
        "Code": 2001,
        "Success": false,
        "SparkQLErrors": [
            {
                "Expression": "SavedSearch Eq '20151441993689437314000000'",
                "Token": "SavedSearch",
                "TokenIndex": 0,
                "Message": "The SavedSearch you specified is not available",
                "Status": "Fatal",
                "SparkQL": null,
                "SparkQLErrors": []
            }
        ]
    }
}

Attribute	Description
`Expression`	The expression where the error was detected. Some syntax errors will not allow a complete expression to be detected, and in those cases, the value will be `null`.
`Token`	The offending token.
`TokenIndex`	The starting position of the offending token in the filter string. Begins at 0.
`Message`	An error message further describing the problem, when more detail can be provided.
`Status`	`Fatal`, `Warn`, or `Dropped`. When `Fatal`, the request could not be completed due to the error. When `Warn`, the field may not have been entirely dropped, but the SparkQL associated with it had dropped fields. This status is most commonly seen when retrieving the results for a saved search. When `Dropped`, the specific error resulted in the parser ignoring the expression. Expressions are dropped most often when an MLS disables a field present in existing searches, so sites running pre-existing saved searches to not appear broken to the end user after the setting has changed.
`SparkQL`	Present when the `Token` references a resource that embeds SparkQL in the search, such as a saved search.
`SparkQLErrors`	Present when the `Token` references a resource that embeds SparkQL in the search, such as a saved search. `TokenIndex`, in this case, will reference the position of the token in the `SparkQL` attribute in the parent `SparkQLErrors` list.