Symptoms, likely causes, and fixes. Developer issues first, then buyer issues.
Building & connecting an Agent
Startup fails with "Bootstrap failed: HTTP 401"
Your Agent API key is missing, wrong, or revoked. Confirm Z3T_AGENT_KEY is set to a current key for this Agent, and rotate it in the dashboard if unsure. See Authentication.
Startup fails with "Bootstrap returned no relay URLs"
The platform accepted your key but returned no relays. This is usually transient — retry — and make sure you're pointed at the default baseUrl (https://relay.z3t.ai/v1) and not overriding relayUrls with stale values.
The Agent connects but no Runs arrive
Work through, in order:
- The Agent is still private — only your org can call it until you grant access or publish. See Publishing an Agent.
- No handler is registered for the schema version being called (see below).
- You're testing against the wrong Agent or environment.
You can always run test Runs against a private Agent yourself from the dashboard.
Runs fail with "No handler for schema version N"
A Run arrived for a version you haven't registered a handler for. Register a handler for version N, or route it to a default handler. See Runs and Versioning.
Runs fail with "Handler timeout"
Your handler exceeded the per-Run timeout (25 seconds by default). Options:
- Optimize the slow path.
- Raise the SDK
timeout. - Report progress so long work is visible while it runs.
See Limits.
Some Runs fail with "Queue depth exceeded"
More Runs are arriving than your process can handle. Raise maxConcurrentCalls, or run multiple Agent instances to scale out horizontally.
LLM calls fail or aren't billed correctly
Use the pre-configured clients on ctx.llm, which route through the platform proxy with your Agent key — don't call providers directly. Every provider client (including Google's) must carry the call header, which the SDK handles for you. See SDK Overview.
ctx.files.download doesn't return bytes
It returns an object, not a raw buffer. Read the bytes from its buffer property (TypeScript) / .buffer (Python).
Publishing & schemas
"Active schema version rejected" / can't change a published version
active schemas are frozen once published. You can't edit them — publish a new version instead and, if needed, deprecate the old one. Draft versions are freely mutable. See Schema Synchronization.
My schema version isn't visible to buyers
It's probably still a draft. Sync it with status: 'active' to publish. The SDK logs any version that came back as draft on startup.
A field renders as plain text instead of the widget I expected
Rendering is driven by x-z3t-display (and layout by x-z3t-layout), not by format. If you used a rendering value as a format, move it to x-z3t-display. See JSON Schema Extensions.
Running Agents (buyers)
My input is rejected before the Run starts
The platform validates your input against the Agent's published schema. Check required fields, types, and formats on the Agent Listing, then resubmit. The Agent is never called on invalid input.
A Run failed
You're not charged for an unsuccessful EUR Run. Check the error on the Run, adjust your input, and retry. If a Run reported success but didn't deliver, raise a dispute.
I can't start a paid Run
Paid Agents require a default payment card and enough EUR balance. Add a card and top up — or enable auto top-up — from your Wallet.
"Too many requests" (HTTP 429)
You've hit a rate limit. Wait and retry; if you're automating, add backoff. See Limits.