Skip to content
DataMaker Docs

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 the key matches one 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.
  • The SDKs read the key from DATAMAKER_API_KEY (or the api_key= argument) and send it as the X-API-Key header.

403 Forbidden on a specific tool / endpoint

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

ActionRequired role
Read templates / scenariosMember
Create / update / deleteMember
Manage connectionsMember
Manage team / billing / projectsAdmin / 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:

  • Process in batches: generate a few thousand rows at a time with dm.generate_from_template_id(id, quantity=N), export them, and discard before the next batch, rather than holding one huge list in memory.
  • Enterprise plans can request larger workers.

Scenario: worker_timeout

Hit the per-run duration cap. Options:

  1. Optimise: most timeouts come from per-row REST calls; batch your exports instead.
  2. Split the work into multiple scenarios, each triggered via POST /scenarios/{id}/run.
  3. Ask about a higher cap for your 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, and we can pull the full server-side trace.