DocTransform

Errors and limits

What each API error code means and which rate limits apply.

Error format

Every /api/v1 failure answers with the same body shape:

{
  "error": "TEMPLATE_NOT_FOUND",
  "message": "No Template with this id exists for this account."
}

Branch on the error field, never on the message text: the message is for a human reading logs.

Error codes

CodeStatusMessage
API_KEY_INVALID401The API Key is malformed, unknown, revoked, or its account is inactive.
API_KEY_MISSING401Send the API Key as an `Authorization: Bearer` header.
APPEND_LOCALE_DISAGREEMENT200A warning, not a failure: some numbers in a part of an Append read differently from the column's locale, and the Run still succeeded.
CHANGE_COUNT_SWING200A warning, not a failure: a count in the Change Report is far off the Template's last run, and the Run still succeeded.
CHECK_NOT_FOUND410That check is gone. Check the file again to fix it.
COLUMN_MATCHED200A warning, not a failure: a column of the file was matched to a Template column by name, ignoring case, spaces and underscores, and the Run still succeeded.
CONCURRENCY_LIMIT_REACHED429This account already has the maximum number of Runs in flight for its plan.
EXCEL_ROW_LIMIT200Excel holds at most 1,048,575 data rows. Export as CSV instead.
EXCEL_TOO_LARGE200This Excel file is too large to write. Export as CSV instead.
EXPORT_LIMIT_REACHED402This account has used all its exports for this month.
FILE_COUNT_LIMIT_EXCEEDED413The request carries more `file` parts than this plan's Append file limit.
FILE_SPLIT_COLUMN_MISSING200The Template's File Split column is not among the columns the output file writes, so no file was written; the failure's `column` names it.
FILE_SPLIT_TOO_LARGE200The Split Parts are too large to hold in one ZIP, so no file was written. Use a smaller row limit per file or a filter.
FILE_SPLIT_TOO_MANY_PARTS200The Template's File Split would write more Split Parts than the 100-file limit, so no file was written; `parts` says how many it needed.
FILE_TOO_LARGE413The uploaded file exceeds this plan's upload size ceiling.
IDEMPOTENCY_KEY_REUSED409This `Idempotency-Key` was already used for a different request.
INSUFFICIENT_SCOPE403The API Key does not carry the scope this operation requires.
INVALID_COLUMN_MAPPING422`column_mapping` must be a JSON object of strings: each key a column of the file, each value a column the Template reads.
INVALID_IDEMPOTENCY_KEY422`Idempotency-Key` must be 1-255 printable characters.
INVALID_PARSE_PARAMS422`delimiter` must be one printable character; `header_row` must be a non-negative integer within the row ceiling.
JOIN_CLOSE_MATCH_LIMIT200A warning, not a failure: close matching stopped at its limit and the values left over stay unmatched, and the Run still succeeded.
JOIN_CLOSE_MATCHES200A warning, not a failure: some rows were matched to a close spelling in a reference table, and the Run still succeeded.
JOIN_FILE_COLUMNS_MISSING422The `file` part for a Join File lacks columns the Template's Join Step needs.
JOIN_FILE_MISSING422No `file` part was sent for a Join File this Template reads. Send one part for each Join File.
JOIN_FILES_LIMIT_EXCEEDED403This Template reads more files than this plan's joining limit allows.
JOIN_FILES_NOT_AVAILABLE403This plan does not include joining files, which this Template's Join Step needs.
JOIN_REPEATED_KEYS200A warning, not a failure: a reference table repeats some keys, each used its first row, and the Run still succeeded.
JOIN_UNMATCHED_ROWS200A warning, not a failure: some rows found no match in a reference table, and the Run still succeeded.
MALFORMED_FILE400The file could not be read: it is empty, corrupt, or not encoded as expected.
NO_SUBSCRIPTION403This account has no active subscription.
OUTPUT_STORAGE_FULL200Too many output files are waiting to be downloaded; try again after some expire.
PIPELINE_FAILED200The pipeline failed while running the Template.
PIVOT_TOO_MANY_VALUES200A Pivot step's header column has more distinct values than the 100-column limit; filter the rows before that step or choose another header column.
RATE_LIMITED429This account has exceeded its request rate limit for this operation.
REFERENCE_TABLE_COLUMN_IN_USE409The new file drops columns that Templates read. Nothing was replaced; add the columns back, or change those Templates first.
REFERENCE_TABLE_COLUMN_MISSING422A column this Template joins is no longer in its reference table. Open the Template and pick the column again.
REFERENCE_TABLE_ID_NOT_FOUND404No Reference Table with this id exists for this account.
REFERENCE_TABLE_NOT_FOUND422A reference table this Template joins does not exist for this account. Open the Template and pick another table.
REFERENCE_TABLE_REFUSED422The new file is over a cap of Reference Tables or cannot be stored as one. Nothing was replaced.
ROW_LIMIT_EXCEEDED413The uploaded file exceeds this plan's row ceiling.
RUN_FILES_AMBIGUOUS422A `file` part fits two of this Template's input files equally, so it cannot be told apart.
RUN_INTERRUPTED200The Run stopped reporting progress before it finished, including when a deploy replaced the server running it.
RUN_NOT_FOUND404No Run with this id exists for this account, or its output has expired.
RUN_TIMEOUT200The Run did not finish within the time limit.
SERVER_BUSY503This worker is at its memory budget; retry shortly.
SUMMARY_SHEET_BROKEN200The Template's Summary sheet cannot be built from this Run's output, so no file was written; the failure's `column` names the column it needs.
SUMMARY_SHEET_NOT_WRITTEN200A warning, not a failure: the Template has a Summary sheet, but it is only added to Excel files, and the Run still succeeded.
SUMMARY_SHEET_ONE_GROUP_PER_ROW200A warning, not a failure: the Summary sheet has more than half as many groups as the data has rows, and the Run still succeeded.
TEMPLATE_COLUMNS_MISSING422The uploaded file is missing one or more columns this Template's operations require.
TEMPLATE_NOT_FOUND404No Template with this id exists for this account.
TEMPLATE_OP_REFUSED422A step in this Template carries a value its operation no longer accepts. Open the Template and correct that step.
TEMPLATE_OUTPUT_AS_SOURCE422A `file` part is this Template's own output, which a Run never accepts as input.
TEMPLATE_TAKES_ONE_FILE422This Template has no Append Step, so it takes exactly one `file` part.
UNREAD_CELLS200A warning, not a failure: a step could not read some dates or numbers, so its result is empty in those rows, and the Run still succeeded.
UNSUPPORTED_FILE_TYPE415This file type is not supported.

Rate and concurrency

  • Using all of your plan’s monthly exports answers 402 EXPORT_LIMIT_REACHED, with a quota object (used, limit, when it resets).
  • Starting more Runs at once than your plan’s Run Concurrency allows answers 429 CONCURRENCY_LIMIT_REACHED.
  • Sending requests faster than your account’s request rate answers a second, separate 429 RATE_LIMITED.
  • A server at its memory budget answers 503 SERVER_BUSY: retry shortly.

Every /api/v1 response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers for the window it was checked against, so a script can back off before it is refused.

Reference tables and joins

  • A reference table holds up to 50000 rows, never more rows than your plan allows per file, in a file of at most 5 MB with cells of at most 1000 characters. A file over a cap, or one that cannot be stored as a table, answers REFERENCE_TABLE_REFUSED and replaces nothing. How many tables you can save depends on your plan, see Plans and limits.
  • A join step matches on 1 to 3 key columns. Close spellings work on one key column only. Close matching stops at the Close-Match Budget of 25,000,000 pairs (distinct unmatched values times distinct table keys): the values left over stay unmatched, nothing is refused, and the Run succeeds with JOIN_CLOSE_MATCH_LIMIT in its warnings.
  • Replacing a table’s rows answers REFERENCE_TABLE_COLUMN_IN_USE when the new file drops a column a Template reads, listing those Templates, and REFERENCE_TABLE_ID_NOT_FOUND for an id that is not yours. Nothing is replaced in either case.

Listing reference tables and replacing their rows never spend your monthly Quota or a Run Concurrency slot. They have their own request rate, which answers 429 RATE_LIMITED when exceeded.

What does not count toward your quota

Listing Templates and polling a Run’s status or output never spend your monthly Quota. Only a Run that finishes and returns a file counts. A refused, failed, timed-out, interrupted or idempotently replayed Run is never charged. The limits of each plan are on Plans and limits.

A File Split writes at most 100 Split Parts. A Run that would write more fails with FILE_SPLIT_TOO_MANY_PARTS, writes no file and is never charged: send the file in chunks of at most max_parts × max_rows rows, one Run each. A split by a column's values has no max_rows to raise: choose a column with fewer values, or filter the rows first.

A File Split by a column the output file does not write (an excluded or dropped column) fails with FILE_SPLIT_COLUMN_MISSING, writes no file and is never charged: keep the column in the output or change the split.

A split whose files are too large to hold in one ZIP fails with FILE_SPLIT_TOO_LARGE, writes no file and is never charged: use a smaller row limit per file or filter the rows.