1.  [Documentation](/en/docs)
2.  [API](/en/docs/api/quickstart)
3.  Errors and limits

# 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."
    }

Copy

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

## Error codes

Code

Status

Message

`API_KEY_INVALID`

401

The API Key is malformed, unknown, revoked, or its account is inactive.

`API_KEY_MISSING`

401

Send the API Key as an \`Authorization: Bearer\` header.

`APPEND_LOCALE_DISAGREEMENT`

200

A 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_SWING`

200

A 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_FOUND`

410

That check is gone. Check the file again to fix it.

`COLUMN_MATCHED`

200

A 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_REACHED`

429

This account already has the maximum number of Runs in flight for its plan.

`DOWNLOAD_LINK_EXPIRED`

410

This download link has expired. Run the template again to get a new file.

`EXCEL_ROW_LIMIT`

200

Excel holds at most 1,048,575 data rows. Export as CSV instead.

`EXCEL_TOO_LARGE`

200

This Excel file is too large to write. Export as CSV instead.

`EXPORT_LIMIT_REACHED`

402

This account has used all its exports for this month.

`FILE_COUNT_LIMIT_EXCEEDED`

413

The request carries more \`file\` parts than this plan's Append file limit.

`FILE_SPLIT_COLUMN_MISSING`

200

The 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_LARGE`

200

The 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_PARTS`

200

The 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_LARGE`

413

The uploaded file exceeds this plan's upload size ceiling.

`IDEMPOTENCY_KEY_REUSED`

409

This \`Idempotency-Key\` was already used for a different request.

`INSUFFICIENT_SCOPE`

403

The API Key does not carry the scope this operation requires.

`INVALID_COLUMN_MAPPING`

422

\`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_KEY`

422

\`Idempotency-Key\` must be 1-255 printable characters.

`INVALID_PARSE_PARAMS`

422

\`delimiter\` must be one printable character; \`header\_row\` must be a non-negative integer within the row ceiling.

`JOIN_CLOSE_MATCH_LIMIT`

200

A warning, not a failure: close matching stopped at its limit and the values left over stay unmatched, and the Run still succeeded.

`JOIN_CLOSE_MATCHES`

200

A warning, not a failure: some rows were matched to a close spelling in a reference table, and the Run still succeeded.

`JOIN_FILE_COLUMNS_MISSING`

422

The \`file\` part for a Join File lacks columns the Template's Join Step needs.

`JOIN_FILE_MISSING`

422

No \`file\` part was sent for a Join File this Template reads. Send one part for each Join File.

`JOIN_FILES_LIMIT_EXCEEDED`

403

This Template reads more files than this plan's joining limit allows.

`JOIN_FILES_NOT_AVAILABLE`

403

This plan does not include joining files, which this Template's Join Step needs.

`JOIN_REPEATED_KEYS`

200

A warning, not a failure: a reference table repeats some keys, each used its first row, and the Run still succeeded.

`JOIN_UNMATCHED_ROWS`

200

A warning, not a failure: some rows found no match in a reference table, and the Run still succeeded.

`MALFORMED_FILE`

400

The file could not be read: it is empty, corrupt, or not encoded as expected.

`NO_SUBSCRIPTION`

403

This account has no active subscription.

`OUTPUT_STORAGE_FULL`

200

Too many output files are waiting to be downloaded; try again after some expire.

`PIPELINE_FAILED`

200

The pipeline failed while running the Template.

`PIVOT_TOO_MANY_VALUES`

200

A 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_LIMITED`

429

This account has exceeded its request rate limit for this operation.

`REFERENCE_TABLE_COLUMN_IN_USE`

409

The new file drops columns that Templates read. Nothing was replaced; add the columns back, or change those Templates first.

`REFERENCE_TABLE_COLUMN_MISSING`

422

A column this Template joins is no longer in its reference table. Open the Template and pick the column again.

`REFERENCE_TABLE_ID_NOT_FOUND`

404

No Reference Table with this id exists for this account.

`REFERENCE_TABLE_NOT_FOUND`

422

A reference table this Template joins does not exist for this account. Open the Template and pick another table.

`REFERENCE_TABLE_REFUSED`

422

The new file is over a cap of Reference Tables or cannot be stored as one. Nothing was replaced.

`ROW_LIMIT_EXCEEDED`

413

The uploaded file exceeds this plan's row ceiling.

`RUN_FILES_AMBIGUOUS`

422

A \`file\` part fits two of this Template's input files equally, so it cannot be told apart.

`RUN_INTERRUPTED`

200

The Run stopped reporting progress before it finished, including when a deploy replaced the server running it.

`RUN_NOT_FOUND`

404

No Run with this id exists for this account, or its output has expired.

`RUN_TIMEOUT`

200

The Run did not finish within the time limit.

`SERVER_BUSY`

503

This worker is at its memory budget; retry shortly.

`SUMMARY_SHEET_BROKEN`

200

The 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_WRITTEN`

200

A 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_ROW`

200

A 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_MISSING`

422

The uploaded file is missing one or more columns this Template's operations require.

`TEMPLATE_NOT_FOUND`

404

No Template with this id exists for this account.

`TEMPLATE_OP_REFUSED`

422

A step in this Template carries a value its operation no longer accepts. Open the Template and correct that step.

`TEMPLATE_OUTPUT_AS_SOURCE`

422

A \`file\` part is this Template's own output, which a Run never accepts as input.

`TEMPLATE_TAKES_ONE_FILE`

422

This Template has no Append Step, so it takes exactly one \`file\` part.

`UNREAD_CELLS`

200

A 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_TYPE`

415

This 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](/en/docs/guides/plans).
*   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](/en/docs/guides/plans).

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.
