Errors

Every error from SOR has one shape:

{
  "request_id": "7f9d1c2e-...",
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Service not found",
    "details": null
  }
}

Field	Notes
request_id	The same id a success would carry.
error.code	A stable, machine-readable string.
error.message	Human-readable. May change; do not match on it.
error.details	Optional structured context: validation errors by field, or, on the Edits API, the refused items by index.

Status codes

Status	When
400	The request is malformed in a way validation could not express.
401	Missing or invalid credential for the surface.
403	Valid credential, but not allowed: wrong business, wrong role, or a policy that refuses.
404	No such resource, or a feature that is off for this business.
409	Conflict: compare-and-swap failed, a claim is held by someone else, a slug is taken.
422	Validation error. details lists the fields.
429	Rate limited. Retry after the interval in Retry-After.
500	Server error. Quote the request_id.

Every endpoint in the reference lists the codes it can return, all with the ErrorResponse body.

On the Edits API

A staged changeset can be partly refused: items that fail validation or compare-and-swap are listed in error.details.items with their index, entity, code, and message, so a caller can fix only those. The MCP server passes this through to the model verbatim.