Sorzio Documentation · Human & AI Ready

Connect once. Enrich, verify, and ship anywhere.

Clear step-by-step guides for Claude, ChatGPT, Cursor, Google Sheets, and our 28-endpoint Platform API (/v1), written for humans and formatted for LLMs.

Connect MCP in 30s Platform API (/v1) Reference

Remote MCP Server · OAuth 2.1

https://www.sorzio.com/api/mcp

Works in Claude Desktop, claude.ai, Claude Code, Cursor, ChatGPT, and Windsurf.

Headless Platform API · OpenAPI 3.1

https://www.sorzio.com/v1

Free sz_test_ sandbox keys · Create account ($20 credit)

Quick Overview

How does Sorzio connect to AI assistants, spreadsheets, and apps?

Full spec +

Sorzio provides three connected surfaces backed by one prepaid balance: a remote OAuth 2.1 MCP server (/api/mcp) with 41 core tools for Claude, ChatGPT, and Cursor; a native Google Sheets add-on for server-side batches and scheduled Flows; and a 28-endpoint REST Platform API (/v1) returning verbatim evidence quotes and SHA-256 source snapshots. Failed rows always bill $0.00.

MCP Tools: 41 + 6
Platform API (/v1): 28 routes
Google Sheets: 25,000
Failed Rows: $0.00

/llms.txt /llms-full.txt OpenAPI 3.1 JSON

Open Interactive Studio Sandbox

01 · Quickstart

Start in 60 seconds: pick how you work.

Best for founders, SDRs, RevOps, and developers working inside Claude, ChatGPT, or Cursor.

Add the remote MCP URL

Paste Sorzio's Streamable HTTP endpoint into Claude, ChatGPT, Cursor, or run one CLI command.

https://www.sorzio.com/api/mcp

Approve OAuth 2.1 in your browser

Ask in plain English

Upload a CSV or link a Google Sheet, preview 3 rows free, and pay $0 for any row that fails.

Enrich these 25 domains, verify emails, and keep deliverable VPs.

No API keys neededJump to MCP client tabs

02 · Model Context Protocol (MCP)

Connect Claude, ChatGPT, Cursor & Windsurf with zero API keys.

Sorzio hosts a remote Streamable HTTP MCP server at https://www.sorzio.com/api/mcp using OAuth 2.1 + PKCE (S256) and RFC 9728 discovery (/.well-known/oauth-protected-resource).

Settings > Connectors > Add custom connectorBrowser OAuth 2.1 + PKCE

1Open Claude Desktop or claude.ai and go to Settings > Connectors.
2Click Add custom connector, name it Sorzio, and paste https://www.sorzio.com/api/mcp.
3Click Connect and approve workspace access in the browser popup. All 41 core tools load immediately.

Starter Prompt to Try First

“Use Sorzio to create a list with 3 B2B SaaS domains, enrich their websites, and draft a 2-sentence outbound opener grounded in their pricing page.”

Remote MCP Server URL

https://www.sorzio.com/api/mcp

Safety rail: Paid MCP runs over $5 always pause for your explicit confirmation, and failed rows bill $0.00.

What your AI can run (41 core tools + 6 Decision Mode tools)

Browse full 47-tool schema catalog →

Account & Cost Control

6 tools

Check balance, browse 300+ models, and see exact pre-flight USD estimates before any run.

get_started, open_dashboard, get_account, list_models, estimate_cost, get_history

Hosted Lists & Google Sheets

9 tools

Upload CSV rows into a Hosted List or inspect connected Google Sheets with column_intelligence.

list_lists, create_list, add_rows, get_rows, export_list, delete_list, purge_lists, list_sheets, read_sheet

Prompts & Batch Execution

13 tools

Crawl 6-page company sites, enrich LinkedIn URLs, verify mailboxes, and run grounded AI prompts.

list_prompts, get_prompt, save_prompt, delete_prompt, preview_prompt, run_ai, run_verify, run_scrape, get_run, cancel_run, retry_failed, get_run_rows, export_run

Flows & Recurring Schedules

10 tools

Chain multi-step DAGs with free checkpoints and run daily or weekly sheet watermarks.

list_flows, get_flow, save_flow, delete_flow, run_flow, get_flow_run, cancel_flow_run, list_schedules, create_schedule, delete_schedule

Hosted Links (1:1 Microsites)

3 tools

Publish personalized prospect teardowns for $0.00 and pay $0.15 only on first verified human open.

list_page_templates, publish_list_pages, get_page_analytics

Decision Mode Calibration

6 tools

Score ICP fit with calibrated probabilities (keep, unsure, reject) at $1.00 / 1k rows base fee.

compile_decision_profile, save_decision_profile, list_decision_profiles, get_decision_profile, preview_decision, run_decide

03 · Spreadsheets & Pipelines

Google Sheets Add-on, Automated Flows & Hosted Links.

Every batch runs server-side rather than inside browser formulas, so sheets never freeze or re-bill on reload. Reference any column header with double curly braces like {{company_url}} or {{linkedin_url}}.

6-Page Website & LinkedIn Enrich

$0.006/site · $0.0075 Co. LI · $0.01 Person LI

Crawls home + about, products, case studies, pricing, and careers at $0 extra subpage cost. Unmatched /in/ profiles write #not_found at $0.

Real Mailbox Verification

$0.01 / email ($10 / 1,000)

Classifies deliverable, catch_all, risky, or undeliverable before downstream AI spend. Unknown or transient timeouts bill $0.

Grounded AI & Decision Mode

from $0.0035/row · $1.00/1k Decision

Run 300+ generative models (with optional 5-provider live web search) or calibrated typesafe-ai/jev-1.14.0 ICP gates ($1.00 / 1k rows base fee).

Scheduled Flows & Hosted Links

Test 3 / 10 / 50 rows · $0 link publish

Chain steps with free checkpoints, schedule daily/weekly watermark runs on Sheets, and publish 1:1 microsites ($0.15 only on first human open).

04 · Headless REST (/v1)

Platform API: 28 endpoints with verbatim evidence quotes.

Authenticate with Authorization: Bearer sz_live_... (or free sz_test_... up to 50 rows). Pass X-Sorzio-Workspace from a platform_parent key to route into isolated customer sub-workspaces.

POST /v1/jobs/estimate

curl -sS -X POST "https://www.sorzio.com/v1/jobs/estimate" \
  -H "Authorization: Bearer $SORZIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"flow":"lead_qual@1","row_count":250}'

HTTP Operations (36 of 36 across 28 /v1 routes)

Method	Endpoint	What it does
GET	/v1/openapi.json	Machine-readable OpenAPI 3.1 contract for all 28 Platform API v1 routes.
GET	/v1/workspaces	List accessible root and child sub-workspaces for the caller key.
POST	/v1/workspaces	Provision a root workspace or an isolated child sub-workspace.
GET	/v1/workspaces/{w}	Read workspace retention, monthly caps, identity mode, and masked webhook secret.
PATCH	/v1/workspaces/{w}	Update workspace retention window, monthly spend cap, or webhook endpoint.
GET	/v1/workspaces/{w}/keys	List active and revoked API key prefixes and metadata for a workspace.
POST	/v1/workspaces/{w}/keys	Mint sz_live_ or sz_test_ API keys scoped to a workspace.
DELETE	/v1/workspaces/{w}/keys/{keyId}	Immediately revoke an API key and write an immutable audit entry.
POST	/v1/workspaces/{w}/webhook-secret/rotate	Rotate whsec_ HMAC signing secret for outbound job webhooks.
GET	/v1/workspaces/{w}/usage	Inspect monthly row usage, billed cents, and remaining cap headroom.
GET	/v1/schemas/templates	List 5 starter templates including contact_deliverability and person_profile.
POST	/v1/schemas	Install a starter template or save a controlled-vocabulary workspace schema.
GET	/v1/schemas	List all schemas registered in the target workspace.
GET	/v1/flows/{id}/versions	List all published immutable versions for a flow.
PUT	/v1/flows/{id}/versions/{v}	Publish an immutable flow version (extract, connector, email_verify, decide).
GET	/v1/flows/{id}/versions/{v}	Fetch an immutable flow definition and SHA-256 content hash.
PUT	/v1/flows/{id}/auto-accept-policy	Configure Wilson 95% CI lower-bound threshold for auto_accepted claims.
POST	/v1/jobs/estimate	Dry-run cost, BYOK detection, sync/async mode, and cap check at $0 spend.
POST	/v1/jobs	Submit <= 10 sync rows (201) or up to 10,000 async background rows (202).
GET	/v1/jobs/{id}	Poll job status, row counters, lockstep billing status, and error summary.
POST	/v1/jobs/{id}/cancel	Cancel a queued or running async job and settle only completed rows.
GET	/v1/jobs/{id}/rows	Paginate per-row status, errors, and secret-redacted input previews.
GET	/v1/jobs/{id}/results	Export verified claims or flat rows as JSON, formula-safe CSV, or NDJSON.
GET	/v1/flows/{id}/gold-sets	List labeled gold-set datasets uploaded for a flow.
POST	/v1/flows/{id}/gold-sets	Upload labeled gold-set examples for precision and CI calibration.
GET	/v1/flows/{id}/versions/{v}/evals	List historical evaluation runs for an immutable flow version.
POST	/v1/flows/{id}/versions/{v}/evals	Run live or sandbox evaluation (<= 15 passes sync, > 15 async background).
GET	/v1/flows/{id}/versions/{v}/evals/{evalId}	Poll sync or async evaluation status, Wilson 95% CI, and billing state.
GET	/v1/flows/{id}/versions/{v}/bakeoffs	List multi-model bake-off runs for an immutable flow version.
POST	/v1/flows/{id}/versions/{v}/bakeoffs	Compare multiple models head-to-head and rank per-field 95% CI winners.
GET	/v1/flows/{id}/versions/{v}/bakeoffs/{bakeoffId}	Poll multi-model bake-off completion and winning model per field.
GET	/v1/flows/{id}/versions/{v}/quality	Read latest completed eval metrics and multi-model bake-off winners.
POST	/v1/match	Match extracted entities against CRM candidates without mutating records.
GET	/v1/workspaces/{w}/audit-logs	Paginate immutable workspace audit events for keys, flows, and erasures.
GET	/v1/snapshots/{hash}	Retrieve content-addressed SHA-256 source text backing any claim quote.
DELETE	/v1/workspaces/{w}/subjects/{key}	Purge all subject rows, claims, and snapshots; returns del_... receipt.

05 · Metering & Throughput

Transparent metering, rate limits & 0% markup BYOK.

$0.00 failed rows

Lockstep hold & settle

Pre-flight holds reserve worst-case cents; settlement charges strictly succeeded rows and refunds unused holds immediately.

0% AI markup BYOK

Pro ($39) & Scale ($99)

Store OpenAI, Anthropic, Google, Mistral, or xAI keys in the AES-256-GCM vault to pay raw provider token cost with $0 base fee.

120 / min per key

600 / min per workspace

Sliding-window headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After on every /v1 response.

06 · Trust & Webhooks

Signed webhooks, formula-safe exports & 1-call GDPR erasure.

Async jobs sign timestamp.rawBody with Sorzio-Signature: t=...,v1=... (300s replay window), CSV exports neutralize spreadsheet formulas (= + @) while preserving negative numbers, and DELETE /v1/workspaces/{w}/subjects/{key} returns an instant del_... erasure receipt.

Node.js HMAC-SHA256 Webhook Verifier

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifySorzioWebhook(rawBody: string, header: string, secret: string): boolean {
  if (!header || typeof header !== "string") return false;
  const parts: Record<string, string> = {};
  for (const item of header.split(",")) {
    const eqIdx = item.indexOf("=");
    if (eqIdx !== -1) parts[item.slice(0, eqIdx).trim()] = item.slice(eqIdx + 1).trim();
  }
  const ts = Number(parts.t);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
  if (!parts.v1 || !/^[a-f0-9]{64}$/i.test(parts.v1)) return false;
  const expected = createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const actualBuf = Buffer.from(parts.v1.toLowerCase(), "hex");
  const expectedBuf = Buffer.from(expected, "hex");
  return actualBuf.length === expectedBuf.length && timingSafeEqual(actualBuf, expectedBuf);
}

07 · Troubleshooting

Plain-English status & error reference.

Code / Cell	Surface	What happened	How to fix
401 unauthorized	REST /v1 & MCP	Missing, expired, or revoked Bearer sz_live_ / sz_test_ or OAuth 2.1 token.	Mint a fresh key in /dashboard/platform or re-run /mcp browser login.
402 insufficient_balance	REST /v1 & Batches	Pre-flight hold exceeds available workspace balance.	Top up balance or enable Auto-Reload in /dashboard/billing, or test with sz_test_.
403 cross_workspace_forbidden	REST /v1	Workspace-scoped key tried to read or write another sub-workspace.	Use a platform_parent key with X-Sorzio-Workspace or a key minted for that tenant.
409 version_immutable	PUT /v1/flows	Published flow version already exists with a different definition.	Increment version (for example /versions/2) instead of mutating /versions/1.
422 refused_data_class	POST /v1/jobs	Row tagged with licensed or restricted data_class blocked by policy.	Supply first-party or permitted data classes configured on the workspace.
429 rate_limit_exceeded	REST /v1	Exceeded 120 req/60s per key or 600 req/60s per workspace.	Respect the Retry-After header (seconds) and batch up to 10,000 rows per job.
#not_found	Sheets & Enrich	Personal LinkedIn /in/ URL had no public profile match.	Billed at $0.00 automatically; add a free Flow checkpoint to skip downstream AI.
#ERROR: reason	Sheets & Enrich	Target website blocked crawlers or timed out across rescue rungs.	Billed at $0.00; click Retry failed rows or switch to deep JS rendering.

FAQ

Documentation & setup FAQ

Answers on OAuth 2.1 MCP connections, LLM-friendly Markdown exports, sandbox testing, and billing safeguards.

MCP Developer Hub →Platform API (/v1) →Help Center →

No. Point your MCP client at https://www.sorzio.com/api/mcp and complete the browser OAuth 2.1 + PKCE (S256) sign-in. Your AI assistant receives scoped access to all 41 core tools without storing static keys in config files.

Click 'Copy page as Markdown' at the top of /docs to copy a structured guide to your clipboard, or point your agent directly at https://www.sorzio.com/llms-full.txt and https://www.sorzio.com/openapi/v1.json.

MCP (/api/mcp) lets humans and AI assistants run interactive outbound lists, Google Sheets sync, Flows, and Hosted Links via OAuth 2.1. Platform API (/v1) is a headless server-to-server REST API for CRMs and SaaS apps using Bearer sz_live_ or sz_test_ keys, isolated sub-workspaces, and verbatim evidence quotes.

In Google Sheets and MCP, Test 3 / 10 / 50 previews rows before full runs, and batches above $5 pause for explicit confirmation. On Platform API /v1, sz_test_ keys run up to 50 sandbox rows at $0.00, and live runs never charge for failed or unmatched rows.

Ready in under 60 seconds

Connect your AI or launch a $0 sandbox.

Start on Free ($0/mo) with $5 instant credit at signup plus $15 with Auto-Reload. Connect Claude, ChatGPT, or Cursor via OAuth 2.1, install the Google Sheets add-on, or mint an sz_test_ key in Platform Studio.

Start free · $20 credit Open Platform Studio

Connect Claude, ChatGPT, Cursor & Windsurf with zero API keys.

Sorzio hosts a remote Streamable HTTP MCP server at https://www.sorzio.com/api/mcp using OAuth 2.1 + PKCE (S256) and RFC 9728 discovery (/.well-known/oauth-protected-resource).

Settings > Connectors > Add custom connectorBrowser OAuth 2.1 + PKCE

1Open Claude Desktop or claude.ai and go to Settings > Connectors.
2Click Add custom connector, name it Sorzio, and paste https://www.sorzio.com/api/mcp.
3Click Connect and approve workspace access in the browser popup. All 41 core tools load immediately.

Starter Prompt to Try First

“Use Sorzio to create a list with 3 B2B SaaS domains, enrich their websites, and draft a 2-sentence outbound opener grounded in their pricing page.”

Remote MCP Server URL

https://www.sorzio.com/api/mcp

Safety rail: Paid MCP runs over $5 always pause for your explicit confirmation, and failed rows bill $0.00.

What your AI can run (41 core tools + 6 Decision Mode tools)

Browse full 47-tool schema catalog →

Account & Cost Control

6 tools

Check balance, browse 300+ models, and see exact pre-flight USD estimates before any run.

get_started, open_dashboard, get_account, list_models, estimate_cost, get_history

Hosted Lists & Google Sheets

9 tools

Upload CSV rows into a Hosted List or inspect connected Google Sheets with column_intelligence.

list_lists, create_list, add_rows, get_rows, export_list, delete_list, purge_lists, list_sheets, read_sheet

Prompts & Batch Execution

13 tools

Crawl 6-page company sites, enrich LinkedIn URLs, verify mailboxes, and run grounded AI prompts.

list_prompts, get_prompt, save_prompt, delete_prompt, preview_prompt, run_ai, run_verify, run_scrape, get_run, cancel_run, retry_failed, get_run_rows, export_run

Flows & Recurring Schedules

10 tools

Chain multi-step DAGs with free checkpoints and run daily or weekly sheet watermarks.

list_flows, get_flow, save_flow, delete_flow, run_flow, get_flow_run, cancel_flow_run, list_schedules, create_schedule, delete_schedule

Hosted Links (1:1 Microsites)

3 tools

Publish personalized prospect teardowns for $0.00 and pay $0.15 only on first verified human open.

list_page_templates, publish_list_pages, get_page_analytics

Decision Mode Calibration

6 tools

Score ICP fit with calibrated probabilities (keep, unsure, reject) at $1.00 / 1k rows base fee.

compile_decision_profile, save_decision_profile, list_decision_profiles, get_decision_profile, preview_decision, run_decide

Google Sheets Add-on, Automated Flows & Hosted Links.

6-Page Website & LinkedIn Enrich

$0.006/site · $0.0075 Co. LI · $0.01 Person LI

Crawls home + about, products, case studies, pricing, and careers at $0 extra subpage cost. Unmatched /in/ profiles write #not_found at $0.

Real Mailbox Verification

$0.01 / email ($10 / 1,000)

Classifies deliverable, catch_all, risky, or undeliverable before downstream AI spend. Unknown or transient timeouts bill $0.

Grounded AI & Decision Mode

from $0.0035/row · $1.00/1k Decision

Run 300+ generative models (with optional 5-provider live web search) or calibrated typesafe-ai/jev-1.14.0 ICP gates ($1.00 / 1k rows base fee).

Scheduled Flows & Hosted Links

Test 3 / 10 / 50 rows · $0 link publish

Chain steps with free checkpoints, schedule daily/weekly watermark runs on Sheets, and publish 1:1 microsites ($0.15 only on first human open).

Method

Endpoint

What it does

GET

/v1/openapi.json

Machine-readable OpenAPI 3.1 contract for all 28 Platform API v1 routes.

GET

/v1/workspaces

List accessible root and child sub-workspaces for the caller key.

POST

/v1/workspaces

Provision a root workspace or an isolated child sub-workspace.

GET

/v1/workspaces/{w}

Read workspace retention, monthly caps, identity mode, and masked webhook secret.

PATCH

/v1/workspaces/{w}

Update workspace retention window, monthly spend cap, or webhook endpoint.

GET

/v1/workspaces/{w}/keys

List active and revoked API key prefixes and metadata for a workspace.

POST

/v1/workspaces/{w}/keys

Mint sz_live_ or sz_test_ API keys scoped to a workspace.

DELETE

/v1/workspaces/{w}/keys/{keyId}

Immediately revoke an API key and write an immutable audit entry.

POST

/v1/workspaces/{w}/webhook-secret/rotate

Rotate whsec_ HMAC signing secret for outbound job webhooks.

GET

/v1/workspaces/{w}/usage

Inspect monthly row usage, billed cents, and remaining cap headroom.

GET

/v1/schemas/templates

List 5 starter templates including contact_deliverability and person_profile.

POST

/v1/schemas

Install a starter template or save a controlled-vocabulary workspace schema.

GET

/v1/schemas

List all schemas registered in the target workspace.

GET

/v1/flows/{id}/versions

List all published immutable versions for a flow.

PUT

/v1/flows/{id}/versions/{v}

Publish an immutable flow version (extract, connector, email_verify, decide).

GET

/v1/flows/{id}/versions/{v}

Fetch an immutable flow definition and SHA-256 content hash.

PUT

/v1/flows/{id}/auto-accept-policy

Configure Wilson 95% CI lower-bound threshold for auto_accepted claims.

POST

/v1/jobs/estimate

Dry-run cost, BYOK detection, sync/async mode, and cap check at $0 spend.

POST

/v1/jobs

Submit <= 10 sync rows (201) or up to 10,000 async background rows (202).

GET

/v1/jobs/{id}

Poll job status, row counters, lockstep billing status, and error summary.

POST

/v1/jobs/{id}/cancel

Cancel a queued or running async job and settle only completed rows.

GET

/v1/jobs/{id}/rows

Paginate per-row status, errors, and secret-redacted input previews.

GET

/v1/jobs/{id}/results

Export verified claims or flat rows as JSON, formula-safe CSV, or NDJSON.

GET

/v1/flows/{id}/gold-sets

List labeled gold-set datasets uploaded for a flow.

POST

/v1/flows/{id}/gold-sets

Upload labeled gold-set examples for precision and CI calibration.

GET

/v1/flows/{id}/versions/{v}/evals

List historical evaluation runs for an immutable flow version.

POST

/v1/flows/{id}/versions/{v}/evals

Run live or sandbox evaluation (<= 15 passes sync, > 15 async background).

GET

/v1/flows/{id}/versions/{v}/evals/{evalId}

Poll sync or async evaluation status, Wilson 95% CI, and billing state.

GET

/v1/flows/{id}/versions/{v}/bakeoffs

List multi-model bake-off runs for an immutable flow version.

POST

/v1/flows/{id}/versions/{v}/bakeoffs

Compare multiple models head-to-head and rank per-field 95% CI winners.

GET

/v1/flows/{id}/versions/{v}/bakeoffs/{bakeoffId}

Poll multi-model bake-off completion and winning model per field.

GET

/v1/flows/{id}/versions/{v}/quality

Read latest completed eval metrics and multi-model bake-off winners.

POST

/v1/match

Match extracted entities against CRM candidates without mutating records.

GET

/v1/workspaces/{w}/audit-logs

Paginate immutable workspace audit events for keys, flows, and erasures.

GET

/v1/snapshots/{hash}

Retrieve content-addressed SHA-256 source text backing any claim quote.

DELETE

/v1/workspaces/{w}/subjects/{key}

Purge all subject rows, claims, and snapshots; returns del_... receipt.

Transparent metering, rate limits & 0% markup BYOK.

$0.00 failed rows

Lockstep hold & settle

Pre-flight holds reserve worst-case cents; settlement charges strictly succeeded rows and refunds unused holds immediately.

0% AI markup BYOK

Pro ($39) & Scale ($99)

Store OpenAI, Anthropic, Google, Mistral, or xAI keys in the AES-256-GCM vault to pay raw provider token cost with $0 base fee.

120 / min per key

600 / min per workspace

Sliding-window headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After on every /v1 response.

Signed webhooks, formula-safe exports & 1-call GDPR erasure.

Node.js HMAC-SHA256 Webhook Verifier

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifySorzioWebhook(rawBody: string, header: string, secret: string): boolean {
  if (!header || typeof header !== "string") return false;
  const parts: Record<string, string> = {};
  for (const item of header.split(",")) {
    const eqIdx = item.indexOf("=");
    if (eqIdx !== -1) parts[item.slice(0, eqIdx).trim()] = item.slice(eqIdx + 1).trim();
  }
  const ts = Number(parts.t);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
  if (!parts.v1 || !/^[a-f0-9]{64}$/i.test(parts.v1)) return false;
  const expected = createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const actualBuf = Buffer.from(parts.v1.toLowerCase(), "hex");
  const expectedBuf = Buffer.from(expected, "hex");
  return actualBuf.length === expectedBuf.length && timingSafeEqual(actualBuf, expectedBuf);
}

Plain-English status & error reference.

Code / Cell	Surface	What happened	How to fix
401 unauthorized	REST /v1 & MCP	Missing, expired, or revoked Bearer sz_live_ / sz_test_ or OAuth 2.1 token.	Mint a fresh key in /dashboard/platform or re-run /mcp browser login.
402 insufficient_balance	REST /v1 & Batches	Pre-flight hold exceeds available workspace balance.	Top up balance or enable Auto-Reload in /dashboard/billing, or test with sz_test_.
403 cross_workspace_forbidden	REST /v1	Workspace-scoped key tried to read or write another sub-workspace.	Use a platform_parent key with X-Sorzio-Workspace or a key minted for that tenant.
409 version_immutable	PUT /v1/flows	Published flow version already exists with a different definition.	Increment version (for example /versions/2) instead of mutating /versions/1.
422 refused_data_class	POST /v1/jobs	Row tagged with licensed or restricted data_class blocked by policy.	Supply first-party or permitted data classes configured on the workspace.
429 rate_limit_exceeded	REST /v1	Exceeded 120 req/60s per key or 600 req/60s per workspace.	Respect the Retry-After header (seconds) and batch up to 10,000 rows per job.
#not_found	Sheets & Enrich	Personal LinkedIn /in/ URL had no public profile match.	Billed at $0.00 automatically; add a free Flow checkpoint to skip downstream AI.
#ERROR: reason	Sheets & Enrich	Target website blocked crawlers or timed out across rescue rungs.	Billed at $0.00; click Retry failed rows or switch to deep JS rendering.