DocTransform

Fehler und Limits

Was jeder Fehlercode der API bedeutet und welche Ratenlimits gelten.

Fehlerformat

Jeder Fehlschlag von /api/v1 antwortet mit derselben Body-Form:

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

Entscheide anhand des Felds error, nie anhand des Nachrichtentexts: Die Nachricht ist für Menschen, die Logs lesen.

Fehlercodes

CodeStatusNachricht
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 und Nebenläufigkeit

  • Die monatlichen Exporte deines Plans aufzubrauchen antwortet 402 EXPORT_LIMIT_REACHED mit einem quota-Objekt (verbraucht, Limit, wann es sich zurücksetzt).
  • Mehr Läufe gleichzeitig zu starten, als die Nebenläufigkeit deines Plans erlaubt, antwortet 429 CONCURRENCY_LIMIT_REACHED.
  • Anfragen schneller zu senden, als es die Rate deines Kontos erlaubt, antwortet mit einem zweiten, eigenen 429 RATE_LIMITED.
  • Ein Server an seinem Speicherbudget antwortet 503 SERVER_BUSY: Versuche es in Kürze erneut.

Jede Antwort von /api/v1 trägt die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset für das Fenster, gegen das sie geprüft wurde, damit ein Skript bremsen kann, bevor es abgelehnt wird.

Referenztabellen und Verbindungen

  • Eine Referenztabelle fasst bis zu 50000 Zeilen, nie mehr Zeilen, als dein Plan pro Datei erlaubt, in einer Datei von höchstens 5 MB mit Zellen von höchstens 1000 Zeichen. Eine Datei über einer Grenze oder eine, die sich nicht als Tabelle speichern lässt, wird mit REFERENCE_TABLE_REFUSED beantwortet und ersetzt nichts. Wie viele Tabellen du speichern kannst, hängt von deinem Plan ab, siehe Pläne und Limits.
  • Ein Verbindungsschritt gleicht über 1 bis 3 Schlüsselspalten ab. Ähnliche Schreibweisen funktionieren nur bei einer Schlüsselspalte. Das ähnliche Zuordnen endet am Budget für ähnliche Zuordnungen von 25,000,000 Paaren (verschiedene nicht zugeordnete Werte mal verschiedene Tabellenschlüssel): Die übrigen Werte bleiben ohne Treffer, nichts wird abgelehnt, und der Lauf gelingt mit JOIN_CLOSE_MATCH_LIMIT in den Warnungen.
  • Das Ersetzen der Zeilen einer Tabelle antwortet mit REFERENCE_TABLE_COLUMN_IN_USE, wenn die neue Datei eine Spalte weglässt, die eine Vorlage liest, und listet diese Vorlagen, und mit REFERENCE_TABLE_ID_NOT_FOUND für eine ID, die nicht dir gehört. In beiden Fällen wird nichts ersetzt.

Das Auflisten von Referenztabellen und das Ersetzen ihrer Zeilen verbrauchen weder dein monatliches Kontingent noch einen Platz bei der Lauf-Parallelität. Sie haben eine eigene Anfragerate, die bei Überschreitung mit 429 RATE_LIMITED antwortet.

Was nicht auf dein Kontingent zählt

Vorlagen aufzulisten und den Status oder die Ausgabe eines Laufs abzufragen verbraucht nie dein monatliches Kontingent. Nur ein Lauf, der fertig wird und eine Datei liefert, zählt. Ein abgelehnter, fehlgeschlagener, abgelaufener, unterbrochener oder idempotent wiedergegebener Lauf wird nie berechnet. Die Limits jedes Plans stehen unter Pläne und Limits.

Eine Dateiaufteilung schreibt höchstens 100 Teildateien. Ein Lauf, der mehr schreiben müsste, scheitert mit FILE_SPLIT_TOO_MANY_PARTS, schreibt keine Datei und wird nie berechnet: Senden Sie die Datei in Stücken von höchstens max_parts × max_rows Zeilen, je ein Lauf. Eine Aufteilung nach den Werten einer Spalte hat kein max_rows, das sich erhöhen ließe: Wählen Sie eine Spalte mit weniger Werten oder filtern Sie zuerst die Zeilen.

Eine Dateiaufteilung nach einer Spalte, die die Ausgabedatei nicht schreibt (ausgeschlossen oder entfernt), scheitert mit FILE_SPLIT_COLUMN_MISSING, schreibt keine Datei und wird nie berechnet: Behalten Sie die Spalte in der Ausgabe oder ändern Sie die Aufteilung.

Eine Aufteilung, deren Dateien zu groß für ein ZIP sind, scheitert mit FILE_SPLIT_TOO_LARGE, schreibt keine Datei und wird nie berechnet: Wählen Sie weniger Zeilen pro Datei oder filtern Sie die Zeilen.