Errors & Troubleshooting

HTTP error envelope

Validation errors from the REST API return 400 with a NestJS-style body:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    { "field": "name", "message": "name is required" }
  ]
}

Two specific conditions carry a structured error_code instead:

`error_code`	HTTP status	Meaning
`QUOTA_EXCEEDED`	403	You’re at a plan limit (`entitlement_key` names which one — see Limits & Quotas).
`RATE_LIMITED`	429	You’ve exceeded your requests/second budget. Honour the `Retry-After` header.

Requests with unknown body fields are rejected with 400 — the API validates strictly (whitelist + reject-unknown), so a typo’d field name fails loudly rather than being silently ignored.

Run error codes

When a reconciliation run fails, the Argo workflow’s exit handler classifies the failure into one of four codes, surfaced in the error.code field of the reconciliation.run.errored and reconciliation.run.finalised events (and in the run-detail API):

Code	Cause	What to do
`TIMED_OUT`	The workflow exceeded its execution deadline.	The job is too large for the default timeout — narrow it (filters, fewer dimensions) or contact us to discuss a longer deadline.
`WORKER_OOM`	A worker pod was killed by the kernel OOM killer (out of memory).	The extraction or comparison working set is too large for the pod’s memory — narrow the job (filters, fewer columns) or contact us.
`QUERY_FAILED`	An extraction step failed — typically a SQL error or a connection issue.	Check the connection is still valid (`connections test`) and that the configured `source_schema`/`source_table` still exist.
`QUOTA_EXCEEDED_STORAGE`	Your tenant’s artifact storage is full.	Free up space (delete old results) or contact us to raise the storage entitlement — see Limits & Quotas.
`UNKNOWN`	Any failure that doesn’t match the above.	Check the run’s logs (`jobs runs logs`) for details; contact support if it’s unclear.

A malformed measure value produces a distinct comparator-level failure:

Code	Cause	What to do
`DATA_TYPE_ERROR`	A column configured as a numeric measure contains a value that can’t convert to a number (in a spreadsheet source — see column typing).	The error names the column, source, and sample offending values — fix or filter out the bad values at the source. This is deliberate: DataRecs never silently coerces an unparseable measure to `NULL` or `0`.

A run that fails for any of these reasons is marked ERRORED, never a misleading COMPLETED/MATCHED — see the run lifecycle for how errored vs. cancelled vs. completed states work.

Common connection failures

Symptom	Cause	Fix
Connection timeout	DataRecs can’t reach the host.	Verify the database is reachable and allowlist DataRecs’ egress IPs (ask support for the current list).
Authentication failed	Wrong username/password, or the user lacks read access.	Re-check credentials; ensure the user can read the tables you intend to reconcile.
`excel_sharepoint` credentials rejected	A field other than `tenant_id`/`site_id` was sent.	Only those two keys are accepted — `client_id`/`client_secret` are platform-level, not per-connection.
BigQuery/Google Sheets impersonation fails	`access_mode` is `impersonation` but `target_service_account_email` is missing.	Supply the target service account email.
`connections test` succeeds but a job run still fails with `QUERY_FAILED`	The configured `source_schema`/`source_table` doesn’t match what’s actually in the database, or permissions changed after the connection was tested.	Re-run `connections test`; verify the table/schema names in the job’s `connections[]` entries.

Next steps

Limits & Quotas — the full quota/rate-limit reference.
Configuring a Reconciliation Job — validation rules enforced at job creation.
Reconciliation Run Lifecycle — the full event and error-code reference for run failures.