Results and recovery
Distinguish returned output, explicit failures and uncertain execution.
API 2.3.3 · Published service contract ↗
Response contract
{
"contract": "sym-response-v1",
"compatibility": "Existing structuredContent and REST success bodies are unchanged. Additive MCP _meta[\"so.sym/response\"] identifies contract, API version, tool, returned/error status and caller requestId when supplied. Returned is not proof of business success or absence of effects.",
"mcp": {
"success": "Read structuredContent. Text content mirrors the JSON metadata. Screenshots also include image content blocks; pixel bytes are excluded from structured/text metadata.",
"error": "Tool execution errors use isError:true and structuredContent.error/status/recovery. HTTP200 can contain an MCP tool error. Protocol, schema and HTTP-admission errors can occur before the handler and need not have tool metadata."
},
"rest": {
"success": "Raw service result, not the MCP content/structuredContent/_meta envelope. Image content GET returns image bytes with private,no-store.",
"error": "HTTP error status plus JSON error; the service error handler includes ok:false and recovery where available. Early host/origin and OAuth-provider errors may use their own envelopes."
},
"payloads": {
"objects": "{result:{kind,...typed action result}}. MCP structuredContent and REST share this same closed envelope. See /docs/objects.md.",
"browser": "Ordinary operation: {result:<native value>}; docs: {documentation:...}; screenshots: MCP flattens safe capture metadata into structuredContent and carries pixels separately. REST retains its original result shape.",
"computer": "Native result under result, except screenshot MCP metadata flattening. Exact operation/session schema comes from the selected Computer Pass.",
"skill": "{skill:{catalogueId,skillId,version,sourceHash,bundleHash},result:{result:{value:<skill output>}}}. Undefined output may omit value. The immutable version manifest.outputSchema describes the skill value, not the surrounding transport.",
"catalogue": "Action-dependent objects. Lists return items and nextCursor; get returns exact version metadata/manifest and source unless includeSource:false. Mutation returns are action-specific, not a universal success boolean.",
"recordings": "Action-dependent list/count/get/asset.get results; recordings are separate from screenshot asset IDs.",
"account": "Current effective account status, not proof of permission to execute any particular Pass."
},
"dynamicBoundaries": [
"Native operation payloads may vary by installed device/version. Open object schemas intentionally preserve that compatibility.",
"Catalogue/recording action results are open objects in MCP outputSchema; their prose contract is not a closed per-action field schema.",
"All browser input schemas are generated; per-verb native output field schemas are not yet universally specified.",
"OAuth-provider, internal administration and playground APIs are outside the public execution OpenAPI document."
],
"recovery": [
"A missing dispatchState does not imply not_started.",
"executionSettled means evaluation returned; effects before an error may have occurred.",
"Never automatically replay an uncertain action or release its window lock.",
"A recovery/reload requires explicit approval and verified reset; it preserves the original unknown receipt."
]
}Error schema
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"status": {
"type": "integer"
},
"ok": {
"const": false
},
"requestId": {
"type": "string"
},
"accountUrl": {
"type": "string"
},
"recovery": {
"type": "string"
},
"dispatchState": {
"enum": [
"not_started",
"started",
"acknowledged",
"unknown"
]
},
"executionSettled": {
"type": "boolean"
},
"validation": {},
"javascriptError": {
"type": "object"
},
"diagnosticId": {
"type": "string"
},
"lockState": {
"type": "string"
},
"retryAfterMs": {
"type": "number"
},
"retry_after_ms": {
"type": "number"
},
"tabId": {
"type": "integer"
},
"stepIndex": {
"type": "integer"
},
"completedSteps": {
"type": "integer"
}
},
"additionalProperties": true
}Recovery
{
"401": "Reconnect Sign in with Sym.",
"402": "Open Sym /home to activate or subscribe; no OAuth retry.",
"403": "Review account plan, selected Pass and native permission; do not widen automatically.",
"409": "Refresh same-Pass capabilities; if already claimed, inspect state before deciding on a new request.",
"429": "Back off; do not fan out retries.",
"503": "Inspect same-Pass connection and operation outcome: a 503 alone does not establish offline state. Do not replay uncertain writes or switch devices."
}Limits
{
"resultJsonCharacters": 8388608,
"skillInputBytes": 32000,
"passPageSize": 50,
"recordingListMax": 50,
"recordingEventTranscriptPageMax": 200,
"recordingAssetMaxBytes": 2097152
}A successful HTTP response is not proof a browser action succeeded. Check isError and structuredContent. Preserve request, Pass and work-session identities; do not replay an uncertain write.
API versions
The API version is 2.3.3. MCP protocol versions, native capability revisions and immutable skill versions are separate. A published operation catalogue is a reference; retrieve sym_pass_docs for the selected device before use.