Debugging

Every response from api.sb carries a request id. From that id, the request log shows each check, the Action it started, the Events it emitted and the logs it wrote.

Start from the request idCopy Anchor Link

Every response carries a Request-Id header, and every problem document repeats it as requestId. The CLI prints it under any error, and the SDK puts it on every result and thrown error as requestId.

shipwatch.dev is a Dataset API of parcel tracking events, sold to online stores by the call. A store reports that switching to the higher plan fails on shipwatch's billing page. The developer copies one line from the failing response, Request-Id: req_7Hk2, and needs nothing else.

npx startup-builder show /requests/req_7Hk2

The request logCopy Anchor Link

The request log holds every request a namespace received, in test and live. It opens in startups.studio, for one Startup or across a whole Portfolio. show prints the same record:

{
  "$id": "https://api.sb/shipwatch.dev/requests/req_7Hk2",
  "at": "2026-10-22T14:03:11Z",
  "method": "POST",
  "path": "/subscriptions/subscription_12/switch",
  "status": 403,
  "key": "pk_live_…a91f",
  "durationMs": 38,
  "gates": [
    { "gate": "key", "verdict": "pass" },
    { "gate": "permission", "verdict": "fail", "rule": "Publishable keys run only public Verbs, and Subscription.switch is not public" }
  ],
  "action": null,
  "events": []
}

gates lists the checks in the order they ran, and the first fail is the answer. Here the billing page sends shipwatch's publishable key from the browser, and that key runs only public Verbs. The fix is to make the call from shipwatch's server, with a secret key, for the signed-in Customer.

Gates, in orderCopy Anchor Link

A call passes up to six gates before its Verb runs. Each verdict names the rule that decided it.

The first four reject at the door, so no Action exists. The last two create one, and the request log links to it.

An Action that waitsCopy Anchor Link

A call that passed every gate but has not finished is a pending Action. Its reason says what it waits for, and the Action records every attempt:

npx startup-builder show /actions/action_31

awaitingSource means an outside service is down, and the platform retries it. awaitingWorker points at an open Task.

awaitingTime shows when its delay window closes. To give up, cancel the Action; to run a failed one again, retry it.

TracesCopy Anchor Link

Send a W3C traceparent header, and the platform joins your trace instead of starting one. Every step under the call reports into it: Workflows, model calls, sandboxes and outbound requests.

A slow call then reads as one timeline in your own tracing tool. Code outside the platform sends spans over OTLP into the same trace. Observability is the capability behind traces and logs.

LogsCopy Anchor Link

Code a Startup runs writes logs, tagged with the request id and the Action. Logs are kept forever.

npx startup-builder logs tail --request req_7Hk2
npx startup-builder logs tail --level error --follow

--follow keeps the stream open. An Agent that debugs reads the same request log, Actions and logs through MCP, with the same ids.

Reproduce in testCopy Anchor Link

To reproduce a failure safely, run the same call in test with the Mode try. It passes the same gates and stores nothing. The request log of a try call shows the verdicts exactly as a recorded call would.

NextCopy Anchor Link

• Errors and testing: every error and how to force it in test.
• Modes: the reasons an Action waits, and what each one waits for.
• Keys: secret, publishable and session keys.