DocTransform

Erros e limites

O que significa cada código de erro da API e quais limites de frequência se aplicam.

Formato do erro

Toda falha de /api/v1 responde com a mesma forma de corpo:

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

Decida pelo campo error, nunca pelo texto da mensagem: a mensagem é para uma pessoa que lê os logs.

Códigos de erro

CódigoStatusMensagem
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.

Frequência e concorrência

  • Esgotar as exportações mensais do seu plano responde 402 EXPORT_LIMIT_REACHED, com um objeto quota (usadas, limite, quando reinicia).
  • Iniciar mais execuções ao mesmo tempo do que a concorrência do seu plano permite responde 429 CONCURRENCY_LIMIT_REACHED.
  • Enviar requisições mais rápido do que a frequência da sua conta responde um segundo 429 RATE_LIMITED, distinto do anterior.
  • Um servidor no limite de memória responde 503 SERVER_BUSY: tente de novo em breve.

Toda resposta de /api/v1 leva os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset da janela contra a qual foi verificada, para que um script possa recuar antes de ser recusado.

Tabelas de referência e uniões

  • Uma tabela de referência aceita até 50000 linhas, nunca mais linhas do que o seu plano permite por arquivo, em um arquivo de no máximo 5 MB com células de no máximo 1000 caracteres. Um arquivo acima de um limite, ou que não pode ser guardado como tabela, responde REFERENCE_TABLE_REFUSED e não substitui nada. Quantas tabelas você pode salvar depende do seu plano, veja Planos e limites.
  • Uma etapa de união casa por 1 a 3 colunas-chave. Grafias parecidas funcionam só com uma coluna-chave. A busca para no orçamento de correspondências parecidas de 25,000,000 pares (valores distintos sem correspondência vezes chaves distintas da tabela): os valores restantes ficam sem correspondência, nada é recusado e a execução dá certo com JOIN_CLOSE_MATCH_LIMIT nos avisos.
  • Substituir as linhas de uma tabela responde REFERENCE_TABLE_COLUMN_IN_USE quando o arquivo novo tira uma coluna que um modelo lê, listando esses modelos, e REFERENCE_TABLE_ID_NOT_FOUND para um id que não é seu. Em ambos os casos nada é substituído.

Listar as tabelas de referência e substituir suas linhas nunca gasta sua cota mensal nem uma vaga de concorrência de execuções. Elas têm a própria taxa de requisições, que responde 429 RATE_LIMITED quando excedida.

O que não conta para sua cota

Listar modelos e consultar o status ou a saída de uma execução nunca gasta sua cota mensal. Só conta uma execução que termina e devolve um arquivo. Uma execução recusada, falha, expirada, interrompida ou repetida por idempotência nunca é cobrada. Os limites de cada plano estão em Planos e limites.

Uma divisão em arquivos escreve no máximo 100 partes. Uma execução que precisaria de mais falha com FILE_SPLIT_TOO_MANY_PARTS, não escreve arquivo algum e nunca é cobrada: envie o arquivo em blocos de no máximo max_parts × max_rows linhas, uma execução por bloco. Uma divisão pelos valores de uma coluna não tem max_rows para aumentar: escolha uma coluna com menos valores ou filtre antes as linhas.

Uma divisão em arquivos por uma coluna que o arquivo de saída não escreve (excluída ou removida) falha com FILE_SPLIT_COLUMN_MISSING, não escreve arquivo algum e nunca é cobrada: mantenha a coluna na saída ou mude a divisão.

Uma divisão cujos arquivos são grandes demais para um ZIP falha com FILE_SPLIT_TOO_LARGE, não escreve arquivo algum e nunca é cobrada: use menos linhas por arquivo ou filtre as linhas.