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 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.