Common errors
Diagnose authentication, generation, connection and execution failures.
Start with the exact operation, HTTP status or run state, selected project and installed release. Keep credentials and raw sensitive records out of diagnostic messages.
Authentication and access
401: verify the host and credential. REST API keys useX-API-Key; the built-in HTTP MCP transport uses a session bearer token.403: inspect permissions, scope and pending approvals. Knowing a resource ID does not grant access.402: inspect the license or usage remediation in the response and the workspace plan.404: check the ID and project; inaccessible resources can also appear not found.
See Workspace access and REST API.
Generation fails or looks wrong
Inspect the field catalogue and type-specific options. Check numeric ranges, Derived references, nested template IDs and source connections. A successful HTTP response can still contain field error markers; validate values before exporting.
The generation response contains columns in live_data, not a row array. If len(result) or Object.keys(result) reports two items, you may be counting the response envelope. See Python conversion.
Connection timeout or TLS failure
Test from the component executing the request. A hosted worker cannot reach a database on your laptop through localhost. Check DNS, routing, firewall rules, credentials and the certificate chain. Configure the deployment's trusted corporate CA where needed; do not disable verification as a routine fix.
Scenario failed, stalled or timed out
Inspect the run log and worker availability separately. Dependency installation can fail before your script starts, and a requirement written in a form the save path refuses is dropped rather than installed; see Python environment.
For memory pressure, process smaller batches or use chunked data jobs. For timeouts, inspect slow target calls and the configured scenario timeout. Cancellation does not undo writes, and a rerun starts at the beginning.
Rate limit or locked resource
For 429, honor Retry-After if supplied and use bounded backoff. The SDKs do not guarantee automatic retries. For 409, inspect the resource state; a locked set must be reviewed and unlocked before changing it.
Missing files or unexpected success
Write outputs under DATAMAKER_WORKSPACE_OUTPUTS, then verify the persisted file. A start acknowledgment is not a completed run; poll the status route. For data jobs, inspect failed/skipped counts even after completion.