rclone limits, behaviour and errors

Beta. The Tarkle backend for rclone is not in any public rclone release yet. It is pending review by rclone’s own maintainers at pull request 10250, so today you can use it only by building rclone from Tarkle’s fork. To build it, follow Install rclone from Tarkle’s fork. This only works for someone comfortable with Go and a terminal.

Set up the remote first with Configure the Tarkle remote. rclone signs in with an API key, described in API keys.

How files, times and hashes are stored

Folders and files on Tarkle are the folders and files rclone sees. Names are case-insensitive: Photos and photos in the same folder are one name.

Modification times are kept to one second. rclone sends the time of the local file with the upload. It can change the time later without uploading the file again, which is what rclone touch relies on.

Tarkle stores a SHA-256 hash of each file. For files up to 100 MiB, Tarkle computes the hash of the stored file and refuses the upload if it differs from the hash rclone sent, and rclone sends the file again. For larger files, the stored hash is the one the uploader sent, and Tarkle does not check it. Because of this, rclone check can compare a local folder with a Tarkle folder by hash, and a normal rclone sync (no --size-only needed) works as expected.

Large files and multipart uploads

Large files travel in parts. Tarkle chooses the part size and the number of parts for each file. rclone sends the parts straight to storage through short-lived links, so file data does not pass through the Tarkle API host.

Up to --tarkle-upload-concurrency parts of one file upload at the same time. Each part is held in memory while it uploads, so memory use per file is about one part times that number.

If a part fails, rclone sends only that part again. If Tarkle reports parts missing when the upload is finished, rclone reads just those parts from the source and sends them.

Versions and duplicate names

What happens when a file has the same name as one already in the folder depends on the plan.

On Free there are no file versions. The new file is saved under a second name first. rclone then deletes the old file, which goes to the bin, and the new file takes the name you used.

On Pro and Agency (Agency includes everything in Pro), where File versioning is on, an upload with the same name becomes a new version of the existing file. The file keeps its place and gets a new version. Tarkle sometimes asks before it replaces a file: when a transfer uses the file, or when a large file has the same name and size as the one in the folder. rclone answers that question itself, with a new version where versions are kept, so you do not see a prompt.

Storage and largest file

The storage and the largest file size depend on the plan of your organization, the same as in the Tarkle app. Compare the plans on the pricing page. This page does not repeat those numbers.

Requests: 600 a minute per key

Every files endpoint allows 600 requests a minute for each key, and all the files endpoints share that count. Uploading one file takes several requests: one to start the upload, the transfer of its parts, and one to complete it, plus the lookups that a sync makes.

When a key goes over the limit, Tarkle answers 429 with a Retry-After header, and rclone waits before it tries again. A large sync can still reach the limit. Lower the number of files rclone moves at the same time, or cap the requests per second:

rclone sync ./photos remote:photos --transfers 2 --checkers 4 --tpslimit 5

Deleting an item in an active transfer

Deleting a file or folder that an active transfer holds is refused with 409 transfer_active. To delete it anyway, add --tarkle-delete-transfers:

rclone sync ./photos remote:photos --tarkle-delete-transfers

The flag also deletes the transfers that hold the item. The link of each deleted transfer stops working for everyone who has it.

Some transfers cannot be deleted this way. A Feedback board, and a paid transfer that has purchases, is refused with 403 protected, even with the flag. Remove or end the transfer in Tarkle first. Deleting a file or folder moves it to the Tarkle bin, and rclone purge moves a folder with its contents to the bin in the same way.

Protected folders and items

Some items cannot be changed through the API, rclone included. A refusal is 403 protected.

The File requests folder is listed and read-only.
Items inside a system folder cannot be changed through the API.
A team folder cannot be renamed, moved or deleted, and a file inside a team folder cannot be deleted.
A folder that an active file request uses cannot be renamed, moved or deleted.

Other system folders do not appear in listings.

Names

A name can be up to 255 bytes in UTF-8. Tarkle refuses an empty name, . and .., a name with / or a control character, and a name that is not valid Unicode. Those answer 400 invalid_name, and a name that is too long answers 400 name_too_long.

rclone also replaces some characters before it sends a name. By default that is a backslash, a space at the start or the end of a name, and invalid UTF-8 bytes.

What the backend does not do

It cannot upload a stream whose size is not known in advance. rclone writes such a stream to a temporary file first and uploads that file.
It stores no custom metadata. The modification time is the only time you can set, and the creation time is read only.
rclone has no command to restore an item from the bin, so restore it in Tarkle.

Errors

Every error has a code. The full list with the HTTP status of each code is in the error codes reference. The table covers the ones rclone can meet.

Code	Status	Cause	What to do
`unauthorized`	401	The key is missing, mistyped, deleted or revoked.	Check the `token` setting. An owner or admin can copy the key again from its menu in Settings, API, or create a new key.
`legacy_token`	401	The key is an older workspace token, which the API no longer accepts.	Create a new key in Settings, API, and put it in `token`.
`no_access`	403	The workspace key is wrong, the person who created the key cannot reach that workspace, or the key is limited to other workspaces.	Check the `workspace` setting. In Settings, API, check the key’s Access.
`forbidden` (missing scope)	403	The key does not hold `files:read` or `files:write`. Older keys can hold fewer permissions.	Create a new key. A new key holds the full set.
`forbidden` (role)	403	The person who created the key has a role in that workspace that cannot make this change.	Ask that person, or an owner or admin, to make the change or to create the key.
`protected`	403	The file or folder is protected, as described above.	Leave it as it is, or change it in Tarkle.
`transfer_active`	409	The item is part of an active transfer.	Use `--tarkle-delete-transfers` to delete the transfer as well.
`conflict`	409	A file with that name is already in the folder.	Nothing, normally. rclone saves a new version on Pro and Agency, and on Free it replaces the old file as described above.
`incomplete`, `finalizing`	409	Parts are missing, or the upload is being finished.	rclone sends the missing parts and asks again.
`file_too_large`	413	The file is larger than the largest file the plan allows.	Compare the plans on the pricing page, or split the file.
`storage_full`	413	There is not enough storage for a new file.	Free up storage in Tarkle, or move to a plan with more storage.
`storage_limit_exceeded`	413	There is not enough storage for a new version of a file. Older versions count toward storage until they expire.	Free up storage in Tarkle, or move to a plan with more storage.
`integrity_mismatch`	422	The stored file’s SHA-256 differs from the one sent.	rclone sends the file again.
`rate_limited`	429	The key made more than 600 requests in a minute.	rclone waits and tries again. Lower `--transfers`, `--checkers` or set `--tpslimit`, as shown above.
`server_error`, `storage_unavailable`, `unavailable`	500, 502, 503	Tarkle or its storage could not answer, or the key could not be checked right now.	rclone retries these. If they keep coming, try again later.
No code	None	The connection failed or Tarkle could not be reached.	Check your network. If you set `url`, check it. rclone retries these too.

Troubleshooting

The workspace setting is empty. A key can reach several workspaces, so rclone needs to know which one to use. It stops and lists the workspace keys and names the key can reach. Put one of those keys in the workspace setting.

The workspace value is a workspace id. Use the 8-character workspace key instead. Tarkle refuses an id with 400 workspace_key_required.

The workspace value is not 8 characters. The workspace key is 8 letters and digits. Any other value answers 400 invalid_workspace.

no_access with a key that looks right. An unknown key and a workspace the key cannot reach give the same answer, so check the key in the list rclone printed. Then check the key’s Access in Settings, API. A key limited to chosen workspaces cannot reach the others.