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
{ "D": { "Success": true, "Results": [ { "ResourceUri": "/servicename/XXXXX" } ] } }
Accepted 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
{ "D": { "Success": false, "Code": 1234, "Message": "Spark API message describing the problem" } }
Error and warning information
{ "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. |