Common errors

The errors you’ll actually hit, in order of frequency.

401 Unauthorized on every call

The API key is wrong, expired, or revoked.

• Check DM_API_KEY is set and matches a key in Settings → API Keys.
• Keys carry their creator’s role; if that user was removed from the project, the key stops working. Generate a new key from a current member.
• For SDKs, the env var name is DM_API_KEY (not DATAMAKER_API_KEY).

403 Forbidden on a specific tool / endpoint

You’re authenticated but missing the role for that action.

Action	Required role
Read templates / scenarios	Member
Create / update / delete	Member
Manage connections	Member
Manage team / billing / projects	Admin / Owner
Export sensitive fields (agent)	Owner OK, or per-chat opt-in

429 Too Many Requests

You’ve hit a rate limit. Response headers tell you what to wait:

X-RateLimit-Remaining: 0
X-RateLimit-Reset:     1714049400
Retry-After:           37

The SDKs retry transient 429 automatically. If you’re seeing it in the UI, you’re likely running an aggressive scenario; back off or upgrade plan.

Generation: validation_error: field 'X' invalid

The generated value didn’t match the field’s options. Common causes:

• A custom regex that has zero satisfying inputs.
• A number with min > max.
• A template field referencing a deleted child template.

Open the field in the editor and run Preview; you’ll see the exact validation message.

Generation: quota_exceeded

You hit the hourly row quota. See Reference → Limits.

Connection: connection_failed: TLS error

For self-signed certs in dev environments, attach the CA to the connection (under TLS settings) — don’t disable verification.

Connection: connection_failed: timeout

DataMaker reaches the public internet. If your DB is behind a VPN / VPC:

• Free / Pro: set up an SSH tunnel or use a managed bastion.
• Enterprise: ask about VPN / PrivateLink / dedicated egress.

Scenario: worker_oom

Your scenario ran out of memory. Workers have a 512 MB default. Solutions:

• Stream rather than buffer — for row in dm.template(t).stream(count=N): instead of dm.generate(template_id=t, count=N) returning a list.
• Process in batches — generate 1k at a time, push, discard.
• Enterprise plans can request larger workers.

Scenario: worker_timeout

Hit the per-run duration cap (5 min Free, 30 min Pro). Three options:

1. Optimise — most timeouts come from per-row REST calls without batching. Use mode="batch".
2. Split the work — multiple scenarios chained via dm.run_scenario().
3. Upgrade plan.

SAP OData: 403 CSRF token validation failed

The CSRF token expired between fetch and modification. DataMaker auto-retries once; if it persists, your auth flow is short-lived (e.g. an OAuth2 client-credentials grant with an unusually short expiry).

See Troubleshooting → CSRF & auth for the deep dive.

SAP OData: 400 Property X is required

Your template doesn’t include a non-nullable property. Open the entity’s metadata view; non-nullable properties without a default need a value.

MCP: tool calls fail silently in the agent

The agent reports “I called the tool but got nothing back”. Causes:

• The MCP server isn’t actually running. Check the agent’s MCP status panel.
• DM_PROJECT_ID is wrong; the tool succeeds but returns an empty list.
• Network — corp proxies sometimes block stdio MCP traffic in unexpected ways.

Restart the agent after fixing the env vars; MCP servers spawn at startup.

Still stuck

• The audit log (Settings → Audit log) shows every action and its outcome. Scope to the last hour, filter to errors.
• Each error response carries an X-Request-ID header (or error.request_id in the body). Include it in support requests — we can pull the full server-side trace.