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ódigo | Status | Mensagem |
|---|---|---|
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. |
Frequência e concorrência
- Esgotar as exportações mensais do seu plano responde
402 EXPORT_LIMIT_REACHED, com um objetoquota(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é
50000linhas, nunca mais linhas do que o seu plano permite por arquivo, em um arquivo de no máximo5 MBcom células de no máximo 1000 caracteres. Um arquivo acima de um limite, ou que não pode ser guardado como tabela, respondeREFERENCE_TABLE_REFUSEDe 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,000pares (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 comJOIN_CLOSE_MATCH_LIMITnos avisos. - Substituir as linhas de uma tabela responde
REFERENCE_TABLE_COLUMN_IN_USEquando o arquivo novo tira uma coluna que um modelo lê, listando esses modelos, eREFERENCE_TABLE_ID_NOT_FOUNDpara 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.