Troubleshoot a managed build and read its receipts

First identify which object failed: the ORD-... request, the BLD-... delivered system, or one UUID run_id. Do not submit a new request or paid run until you know whether the original one was stored.

Request-form problems

Message or symptom	Meaning	What to do
Complete every required request field	A required identity or scope field is missing or invalid.	Review name, work email, company, build name, outcome, starting point, policy, and cadence.
Choose valid managed-build options	A saved or stale form contains an unsupported option.	Reload the live form and choose from its current options.
Expected return count must be between 1 and 100,000	Volume is outside the request contract.	Enter the expected returned records in the supported range.
Attachments must be PDF, DOCX, CSV, or XLSX and no larger than 10 MB	File type or size is invalid.	Remove the file or upload one supported file within the limit.
The pricing rules changed	The server’s current estimate does not match the displayed estimate.	Review the new lane, reasons, and price before submitting. No order is created at the stale price.
This request was already received	A matching email submitted another request within the duplicate-protection window.	Keep the first receipt and wait; do not submit repeatedly.
Request `ORD-...` was saved, but delivery needs operator review	The request record exists but a confirmation or notification step failed.	Save the order ID and contact support. Do not create a duplicate request.

Build and run errors

Status or error	Meaning	What to do
`401 unauthorized`	The API key is missing or invalid.	Use a current key from the correct workspace. Never send the full key to support.
`AUTH_002` / HTTP `403`	The key can read the build but cannot spend credits.	Use a write-capable or `spend:credits` key approved for the workspace.
`NOT_FOUND` / HTTP `404`	The build or run is not a Final Build in this workspace, or the ID is wrong.	Confirm the selected workspace and exact ID.
`BUILD_NOT_READY`	The requested system has not reached Final Build.	Return to the build lifecycle and complete the approval/finalization steps.
`INSUFFICIENT_CREDITS` / HTTP `402`	The workspace cannot reserve the fixed run price.	Check Billing and add or approve credits before a new attempt. No run was dispatched.
`APPROVAL_REQUIRED`	An MCP live run was requested without spend confirmation.	Inspect the fixed price, then retry with `confirm_spend: true` if approved.
`SPEND_LIMIT_EXCEEDED`	The fixed price is higher than `max_credits`.	Raise the cap only after explicit price approval.
`IDEMPOTENCY_CONFLICT`	The same key was reused for different input or a different build.	Use a new key for a genuinely new intended run; keep the old key for recovery only.
`PAYLOAD_TOO_LARGE` / HTTP `413`	JSON input exceeds 256 KiB.	Split the input according to the delivered runbook.
`DISPATCH_FAILED` / HTTP `503`	The reservation could not be dispatched.	Keep the response and run context. The reservation is refunded; recover before attempting again.

Read the run receipt

A managed-build run can be dispatching, queued, running, completed, or failed.

Save these fields:

run_id and build_id;
run status and Trigger execution ID;
result run ID when available;
fixed credits charged and Clay-credit budget;
billing status;
created, started, and completed timestamps;
error text;
execution receipt and returned result rows.

queued proves dispatch was accepted, not that results exist. completed proves the routine reached a terminal state, but returned records still need the evidence and QA checks in the delivered runbook. failed should be recovered and diagnosed before a new paid run.

If a client times out

Do not assume that no work or spend occurred. Recover the existing run:

REST: GET /v1/managed-build-runs/{run_id}
MCP: get_managed_build_run
CLI: signaliz builds status --run-id RUN_UUID
SDK: getManagedBuildRun(runId)

Reuse the original idempotency key only when you are recovering the same intended run with the same build and input.

What to send support

Send:

the ORD-..., BLD-..., or UUID run_id;
the selected workspace name;
surface used: request form, REST, MCP client, CLI, or SDK;
timestamp and timezone;
HTTP status and error code;
idempotency-key prefix, not the full key when it contains private data;
whether the problem happened before or after price approval;
sanitized input shape and expected output;
the last observed billing status.

Never send a full API key, OAuth token, private keyed MCP URL, password, or unrestricted customer-system credential.

Start again from What are Signaliz Managed Builds?.