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
Failure with additional details (deprecated)

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 elaborates on why a request was unsuccessful, or to provide warnings about a successful response.

Failure with Errors example

{
    "D": {
        "Success": false,
        "Code": 1234,
        "Message": "Spark API message describing the problem",
        "Errors": [
            {
                "Type": "InvalidRecord",
                "Record": {
                    /* Record or part of recrod 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",
                        "Attribute": "BathsTotal",
                        "Message": "Field is required",
                        "Status": "Fatal",
                        "Display": {
                          "Message": "Please enter a value",
                          "Documentation": "There are many fields the that require values before a listing may be accepted. This happens to be one of them.",
                          "DocumentationUri": "http://example.com/listingrules/further_reading"
                        },
                        "Rule": {
                            "Id": 1,
                            "ResourceUri": "/v1/listings/rules/1",
                            "Group": null,
                            "Domain": null,
                            "Field": "BathsTotal"
                        }
                    }
                ]
            }
        ]
    }
}

Success with Errors example

{
    "D": {
        "Results": [
            {
                "ResourceUri": "/v1/savedsearches/20200000000000000000000002",
                "Id": "20200000000000000000000002",
                "OwnerId": "20200000000000000000000001",
                "Name": "Saved Search",
                "Description": null,
                "ContactIds": [],
                "UnsubscribedContactIds": [],
                "ModificationTimestamp": "2021-02-08T17:27:04Z",
                "Filter": "MapOverlay Eq '20200000000000000000000003' And City Eq 'Fargo' And ListPrice Ge 10000.00 And MlsStatus Eq 'Active' And PropertyType Eq 'A'",
                "Annotations": [],
                "QuickSearchId": "20200000000000000000000003",
                "Tags": [],
                "Provided": false,
                "CreatedTimestamp": "2020-11-16T17:16:11+00:00",
                "LastRunTimestamp": "2021-01-12T06:00:00Z",
                "BookmarkTimestamp": null,
                "ProtectedFromDeletion": false
            }
        ],
        "Success": true,
        "Errors": [
            {
                "Type": "InvalidRecord",
                "Message": null,
                "Status": "Warn",
                "Record": {
                  "Filter": "ListPrice Gt 100000",
                  "OwnerId": "20000426143505724628000000",
                  "Name": "EE Junk Search",
                  "Annotations": [
                    {
                        "Type": "Shape",
                        "Match": {
                            "Substring" => "MapOverlay Eq '20200000000000000000000007'"
                        },
                        "Attributes": {
                            "Color": "0077D9",
                            "Label": "Dutch Elms Subdivision"
                        }
                    }
                  ]
                },
                "Errors": [
                    {
                        "Type": "SavedSearchAnnotationRejected",
                        "Message": "An Annotation was rejected because its Match is missing or does not match the Filter.",
                        "Status": "Warn",
                        "Record": {
                            "Type": "Shape",
                            "Match": {
                                "Substring" => "MapOverlay Eq '20200000000000000000000007'"
                            },
                            "Attributes": {
                                "Color": "0077D9",
                                "Label": "Dutch Elms Subdivision"
                            }
                        }
                    }
                ]
            }
        ]
    }
}

Field	Supported Types	Description
`Type`	All	The error type.
`Message`	All	An additional developer-friendly message sometimes provided along with the error data.
`Status`	All	Optionally, an indication of the severity of the error, either `Fatal` or `Warn`.
`Display`	All	Optionally, an additional user-friendly attribute which may include a `Message`, `Documentation`, and `DocumentationUri`.
`Attribute`	`InvalidAttribute`, `RuleViolation`	The invalid attribute present (or missing) from the `POST` or `PUT` data.
`Errors`	`InvalidRecord`	A list of `InvalidAttribute` or `RuleViolation` errors for the `Record`.
`Record`	`InvalidRecord`	The `POST` or `PUT` data that failed validation.
`Rule`	`RuleViolation`	The rule that triggered the error.

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` or `RuleViolation` 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 `Rule` attribute for resource-specific rules, such as Listing Rules.
`SavedSearchAnnotationRejected`	A proposed or existing `SavedSearch Annotation` is or became invalid, for instance because the `Filter` substring it is associated with is no longer present in the `Filter.`

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.

Failure with additional details (deprecated)

Especially during failures with listing updates, additional information about why a request failed may be present in the Details attribute. The various types of response details are documented below.

{
    "D": {
        "Success": false,
        "Code": 1234,
        "Message": "Spark API message describing the problem",
        "Details": [
          {
            "ListPrice": [
              {
                  "RuleName": "MaxValue",
                  "RuleUnits": null,
                  "DetailType": "Violation",
                  "RuleValue": 1000000,
                  "RuleField": null,
                  "RuleFieldValue": null,
                  "Value": 1000001
              }
            ]
          }
        ]
    }
}

Violations

Violations occur when an MLS-defined constraint is violated during a data update. Each violation is listed under its corresponding field, so that there may be multiple fields in violation of a rule and multiple violations for a single field. See the ListPrice example above.

Violation Field	Description
`DetailType`	Always `Violation`.
`RuleName`	The name of the rule that was violated. See the table below for more information.
`RuleValue`	The value, or setting, for the rule definition. For instance, if `RuleName` is `MaxDaysBefore`, this might be `2` to signify "two days."
`RuleUnits`	Often `null`, this field denotes how to interpret `RuleValue` when the `RuleName` itself leaves ambiguity. This may be either `Days`, `Months` or `Years`.
`RuleField`	When populated, the value of this field is used in place of the default value (the original value, the current date, etc., based on the rule). For instance, if the `RuleName` is `MaxDaysBefore`, and `RuleField` is `BeginDate`, the `RuleValue` is the maximum number of days the violated field can be before the listing's begin date.
`RuleFieldValue`	When `RuleField` is present, this is the value in that field.
`Value`	The value for the field that failed the constraint check.

RuleField overrides the default value
Recall that, for fields that support an optional RuleField, the default check (on the current date, the listing'S original value for that field, and so forth) will be replaced with a check against the field specified by RuleField instead.

Rule Name	Has `RuleUnits`?	Supports `RuleField`?	Description
DisallowDecimal	No	No	Forbids decimal values.
LargerOnly	No	Yes	Requires a new value be greater than the previous value.
LargerOrEqualOnly	No	Yes	Requires a new value be greater than or equal to the previous.
MaxDaysAfter	No	Yes	The maximum number of days after the current date the value may be changed to.
MaxDaysBefore	No	Yes	The maximum number of days before the current date the value may be changed to.
MaxDecreasePercent	No	No	The limit the value can be decreased in relation to its current value.
MaxDecreaseValue	No	No	The limit the value can be reduced below its current value.
MaxIncreasePercent	No	No	The limit the value can be increased in relation to its current value.
MaxIncreaseValue	No	No	The limit the value can be increased above its current value.
MaxLength	No	No	The character limit for the field.
MaxTimeAfterToday	Days, Months, or Years	No	The maximum amount of time the date or timestamp field can be before today.
MaxTimeBeforeToday	Days, Months, or Years	No	The maximum amount of time the date or timestamp field can be beyond today.
MaxValue	No	No	The maximum value for a field.
MinDaysAfter	No	Yes	The minimum number of days after the current date the value must be changed to.
MinDaysBefore	No	Yes	The minimum number of days before the current date the value must be changed to.
MinDecreasePercent	No	No	The minimum percentage decrease the value must have in relation to its current value.
MinDecreaseValue	No	No	The minimum decrease the value must have in relation to its current value.
MinIncreasePercent	No	No	The minimum percentage increase the value must have in relation to its current value.
MinIncreaseValue	No	No	The minimum increase the value must have in relation to its current value.
MinLength	No	No	The minimum character length for the field.
MinValue	No	No	The minimum value for a field.
RequireDecimal	No	No	A decimal value is required for this field (e.g. integers are not allowed).
RequireTwoDecimal	No	No	The value for this field must contain two decimal places
SmallerOnly	No	Yes	Requires a new value be less than the previous value.
SmallerOrEqualOnly	No	Yes	Requires a new value be less than or equal to the previous value.