---
title: "Errors"
description: "Every Tarkle API error is an RFC 9457 problem document with a stable code."
---

> Documentation Index
> Fetch the complete documentation index at: https://tarkle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

The Tarkle API reports failures as `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)). 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`](/docs/api/errors/invalid_request) | 400 | A field is missing, has the wrong type or is out of range. |
| [`invalid_workspace`](/docs/api/errors/invalid_workspace) | 400 | The workspace value is malformed. A key is eight lowercase letters and digits (GET /workspaces lists them). |
| [`workspace_required`](/docs/api/errors/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`](/docs/api/errors/workspace_key_required) | 400 | A workspace id was sent where the eight-character workspace key is required. |
| [`conflicting_workspace`](/docs/api/errors/conflicting_workspace) | 400 | The workspace is named twice with different values, for example in the header and in the query. |
| [`not_supported`](/docs/api/errors/not_supported) | 400 | The operation does not apply to this item, for example a modification time on a folder. |
| [`invalid_name`](/docs/api/errors/invalid_name) | 400 | The name is empty, is . or .., contains / or control characters, or is not valid Unicode. |
| [`name_too_long`](/docs/api/errors/name_too_long) | 400 | The name is longer than 255 bytes in UTF-8. |
| [`invalid_destination`](/docs/api/errors/invalid_destination) | 400 | A folder cannot be moved into itself or one of its own subfolders. |
| [`version_too_large`](/docs/api/errors/version_too_large) | 400 | The file is too large to save as a new version. |
| [`confirmation_required`](/docs/api/errors/confirmation_required) | 400 | A destructive or publishing step needs its confirmation: confirm_public: true to make a brand public, confirm_delete: true to delete a brand. |
| [`unauthorized`](/docs/api/errors/unauthorized) | 401 | The token is missing, malformed, invalid or revoked. |
| [`legacy_token`](/docs/api/errors/legacy_token) | 401 | The token is an older workspace token and no longer works. Create a new token in Settings > API. |
| [`forbidden`](/docs/api/errors/forbidden) | 403 | The token lacks the scope this operation needs, or its creator's role in the workspace is not enough. |
| [`token_without_scopes`](/docs/api/errors/token_without_scopes) | 403 | The token was created before scopes existed. Create a new token and choose its scopes. |
| [`no_access`](/docs/api/errors/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. |
| [`workspace_suspended`](/docs/api/errors/workspace_suspended) | 403 | The workspace is suspended, so its API is closed as well. Contact support or the workspace owner. |
| [`protected`](/docs/api/errors/protected) | 403 | The item is protected (system, request, team or transfer folders) and cannot be changed through the API. details.kind says why. |
| [`domain_taken`](/docs/api/errors/domain_taken) | 409 | The domain is already used by another brand or another part of Tarkle, or it is attached elsewhere. details.reason names which. |
| [`domain_rejected`](/docs/api/errors/domain_rejected) | 422 | The hosting provider refused the domain. |
| [`domain_provider_error`](/docs/api/errors/domain_provider_error) | 502 | The hosting provider could not remove the domain. The brand keeps it; retry. |
| [`file_not_uploaded`](/docs/api/errors/file_not_uploaded) | 409 | Nothing was found at the upload address. PUT the file to the url, then complete the upload. |
| [`invalid_file`](/docs/api/errors/invalid_file) | 422 | The uploaded file is too large, the wrong type or not what its name says. The message names the reason and the stored file is removed. |
| [`not_found`](/docs/api/errors/not_found) | 404 | The item, upload or brand does not exist in this workspace. |
| [`conflict`](/docs/api/errors/conflict) | 409 | The request clashes with the current state, for example a file with the same name exists. details lists the choices. |
| [`name_taken`](/docs/api/errors/name_taken) | 409 | A sibling with this name already exists in the folder. |
| [`ambiguous_path`](/docs/api/errors/ambiguous_path) | 409 | Two folders on the path share a name, so the path points at more than one item. Use ids. |
| [`transfer_active`](/docs/api/errors/transfer_active) | 409 | The item is part of an active transfer. details.confirm_with names the field that confirms deleting those transfers. |
| [`incomplete`](/docs/api/errors/incomplete) | 409 | Not every part has arrived. details.missing_parts lists the parts still to send. |
| [`empty_version_not_supported`](/docs/api/errors/empty_version_not_supported) | 409 | An empty file cannot be saved as a new version. details.choices lists what to send instead. |
| [`size_unreadable`](/docs/api/errors/size_unreadable) | 409 | The source file's size could not be read. |
| [`parent_unavailable`](/docs/api/errors/parent_unavailable) | 409 | The folder the item was in is in the bin or gone. Restore that folder first. |
| [`not_multipart`](/docs/api/errors/not_multipart) | 409 | The upload is a single PUT and has no parts to sign. |
| [`not_deleted`](/docs/api/errors/not_deleted) | 409 | Only an item in the bin can be restored. |
| [`not_an_api_upload`](/docs/api/errors/not_an_api_upload) | 409 | The upload was not started through the API. |
| [`folder_unresolved`](/docs/api/errors/folder_unresolved) | 409 | The folder of the file could not be located. |
| [`finalizing`](/docs/api/errors/finalizing) | 409 | The upload is already being completed. Retry shortly. |
| [`expired`](/docs/api/errors/expired) | 410 | The upload session or the bin retention window has passed. |
| [`upload_expired`](/docs/api/errors/upload_expired) | 410 | The upload is finished or expired. Start it again. |
| [`failed`](/docs/api/errors/failed) | 410 | The upload failed. Start it again. |
| [`file_too_large`](/docs/api/errors/file_too_large) | 413 | The file is larger than the plan allows. |
| [`storage_full`](/docs/api/errors/storage_full) | 413 | There is not enough storage left. details.limit may carry the plan's limit in bytes. |
| [`too_large`](/docs/api/errors/too_large) | 413 | A recursive listing covers more folders than one call can return. List a smaller folder. |
| [`integrity_mismatch`](/docs/api/errors/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`](/docs/api/errors/size_mismatch) | 422 | The stored size differs from the size announced when the upload started. |
| [`idempotency_in_progress`](/docs/api/errors/idempotency_in_progress) | 409 | A request with the same Idempotency-Key has not finished. Wait Retry-After seconds and send it again; you get its answer. |
| [`idempotency_key_reused`](/docs/api/errors/idempotency_key_reused) | 422 | The Idempotency-Key was already used for a different request (another path, query, workspace or body). Use a new key. |
| [`rate_limited`](/docs/api/errors/rate_limited) | 429 | Too many requests in this minute. Wait Retry-After seconds. |
| [`too_many_uploads`](/docs/api/errors/too_many_uploads) | 429 | Too many uploads are open at once. Finish or abort some first. |
| [`file_not_found`](/docs/api/errors/file_not_found) | 404 | The file the new version belongs to does not exist any more. |
| [`upload_not_found`](/docs/api/errors/upload_not_found) | 404 | The version upload does not exist or was cleaned up. Start it again. |
| [`version_unavailable`](/docs/api/errors/version_unavailable) | 404 | The version this upload was based on is no longer available. |
| [`file_in_transfer`](/docs/api/errors/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`](/docs/api/errors/upload_in_progress) | 409 | Someone else is already uploading a new version of this file. Retry shortly. |
| [`current_version_changed`](/docs/api/errors/current_version_changed) | 409 | The file got another version while this upload was running. Upload again. |
| [`storage_usage_unreadable`](/docs/api/errors/storage_usage_unreadable) | 409 | Storage usage could not be verified, so nothing was saved. Retry. |
| [`storage_limit_exceeded`](/docs/api/errors/storage_limit_exceeded) | 413 | There is not enough storage for this version. Older versions count toward storage until they expire. |
| [`version_failed`](/docs/api/errors/version_failed) | 500 | The new version could not be saved. Retry; if it persists, contact support. |
| [`server_error`](/docs/api/errors/server_error) | 500 | Something went wrong on our side. Retry; if it persists, contact support. |
| [`storage_unavailable`](/docs/api/errors/storage_unavailable) | 502 | The storage backend failed. Nothing was created; retry. |
| [`unavailable`](/docs/api/errors/unavailable) | 503 | The endpoint is switched off or the plan could not be confirmed. Retry later. |
| [`entitlement_unresolved`](/docs/api/errors/entitlement_unresolved) | 503 | The plan could not be confirmed. Retry. |

Source: https://tarkle.com/docs/api/errors/index.mdx