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
| 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 aquotaobject (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
50000rows, never more rows than your plan allows per file, in a file of at most5 MBwith cells of at most 1000 characters. A file over a cap, or one that cannot be stored as a table, answersREFERENCE_TABLE_REFUSEDand 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,000pairs (distinct unmatched values times distinct table keys): the values left over stay unmatched, nothing is refused, and the Run succeeds withJOIN_CLOSE_MATCH_LIMITin its warnings. - Replacing a table’s rows answers
REFERENCE_TABLE_COLUMN_IN_USEwhen the new file drops a column a Template reads, listing those Templates, andREFERENCE_TABLE_ID_NOT_FOUNDfor 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.