Errors | Tarkle Docs

The Tarkle API reports failures as application/problem+json (RFC 9457). Each response has type, title, status, detail, code and, when it helps, instance. The type address points at the page for that code. The older { "error": { "code", "message" } } envelope is still returned in the same body, so existing clients keep working.

Code	Status	Meaning
`invalid_request`	400	A field is missing, has the wrong type or is out of range.
`invalid_workspace`	400	The workspace value is malformed. A key is eight lowercase letters and digits (GET /workspaces lists them).
`workspace_required`	400	No workspace key was sent. Send X-Workspace-Key (or workspace_key) on every call that works inside a workspace.
`workspace_key_required`	400	A workspace id was sent where the eight-character workspace key is required.
`conflicting_workspace`	400	The workspace is named twice with different values, for example in the header and in the query.
`not_supported`	400	The operation does not apply to this item, for example a modification time on a folder.
`invalid_name`	400	The name is empty, is . or .., contains / or control characters, or is not valid Unicode.
`name_too_long`	400	The name is longer than 255 bytes in UTF-8.
`invalid_destination`	400	A folder cannot be moved into itself or one of its own subfolders.
`version_too_large`	400	The file is too large to save as a new version.
`confirmation_required`	400	Making a brand public needs confirm_public: true in the request.
`unauthorized`	401	The token is missing, malformed, invalid or revoked.
`legacy_token`	401	The token is an older workspace token and no longer works. Create a new token in Settings > API.
`forbidden`	403	The token lacks the scope this operation needs, or its creator’s role in the workspace is not enough.
`token_without_scopes`	403	The token was created before scopes existed. Create a new token and choose its scopes.
`no_access`	403	The workspace key is unknown, or the person who created the token cannot access that workspace. Both answer the same, so keys cannot be probed.
`protected`	403	The item is protected (system, request, team or transfer folders) and cannot be changed through the API. details.kind says why.
`not_found`	404	The item, upload or brand does not exist in this workspace.
`conflict`	409	The request clashes with the current state, for example a file with the same name exists. details lists the choices.
`name_taken`	409	A sibling with this name already exists in the folder.
`ambiguous_path`	409	Two folders on the path share a name, so the path points at more than one item. Use ids.
`transfer_active`	409	The item is part of an active transfer. details.confirm_with names the field that confirms deleting those transfers.
`incomplete`	409	Not every part has arrived. details.missing_parts lists the parts still to send.
`empty_version_not_supported`	409	An empty file cannot be saved as a new version. details.choices lists what to send instead.
`size_unreadable`	409	The source file’s size could not be read.
`parent_unavailable`	409	The folder the item was in is in the bin or gone. Restore that folder first.
`not_multipart`	409	The upload is a single PUT and has no parts to sign.
`not_deleted`	409	Only an item in the bin can be restored.
`not_an_api_upload`	409	The upload was not started through the API.
`folder_unresolved`	409	The folder of the file could not be located.
`finalizing`	409	The upload is already being completed. Retry shortly.
`expired`	410	The upload session or the bin retention window has passed.
`upload_expired`	410	The upload is finished or expired. Start it again.
`failed`	410	The upload failed. Start it again.
`file_too_large`	413	The file is larger than the plan allows.
`storage_full`	413	There is not enough storage left. details.limit may carry the plan’s limit in bytes.
`too_large`	413	A recursive listing covers more folders than one call can return. List a smaller folder.
`integrity_mismatch`	422	The stored file’s SHA-256 differs from the one sent. details.expected and details.stored may carry both hashes.
`size_mismatch`	422	The stored size differs from the size announced when the upload started.
`rate_limited`	429	Too many requests in this minute. Wait Retry-After seconds.
`too_many_uploads`	429	Too many uploads are open at once. Finish or abort some first.
`file_not_found`	404	The file the new version belongs to does not exist any more.
`upload_not_found`	404	The version upload does not exist or was cleaned up. Start it again.
`version_unavailable`	404	The version this upload was based on is no longer available.
`file_in_transfer`	409	A transfer uses this file. Confirm the transfer update in the app, or switch on automatic transfer updates in the workspace’s file settings.
`upload_in_progress`	409	Someone else is already uploading a new version of this file. Retry shortly.
`current_version_changed`	409	The file got another version while this upload was running. Upload again.
`storage_usage_unreadable`	409	Storage usage could not be verified, so nothing was saved. Retry.
`storage_limit_exceeded`	413	There is not enough storage for this version. Older versions count toward storage until they expire.
`version_failed`	500	The new version could not be saved. Retry; if it persists, contact support.
`server_error`	500	Something went wrong on our side. Retry; if it persists, contact support.
`storage_unavailable`	502	The storage backend failed. Nothing was created; retry.
`unavailable`	503	The endpoint is switched off or the plan could not be confirmed. Retry later.
`entitlement_unresolved`	503	The plan could not be confirmed. Retry.