Errors

Every error has the same shape. code is stable and meant for your code; message, when present, is a human explanation and may change.

{
    "status": "error",
    "code": "UPGRADE_REQUIRED",
    "message": "Custom metadata is available on Pro and Enterprise plans only."
}

Retry only on 429 and 5xx, with backoff. Every 4xx other than 429 means the request itself has to change.

Authentication and limits

Code	HTTP	Meaning
`ACCESS_DENIED`	401	The credential is missing or was not recognized.
`PERMISSION_DENIED`	401	The account has no active paid plan, which this action needs.
`MISSING_SCOPE`	403	The API key lacks the scope this route needs. See Authentication.
`RESOURCE_NOT_ALLOWED`	403	The API key is restricted to specific applications.
`UPLOAD_TOKEN_NOT_ALLOWED`	403	Upload tokens only work on upload routes.
`UPLOAD_TOKEN_USED`	401	The upload token has no uses left. An expired token answers `ACCESS_DENIED`.
`ACCOUNT_BLOCKED`	403	The account is blocked from storing files. Contact support.
`UPGRADE_REQUIRED`	403	The option is not part of your plan. The `message` names the plan that unlocks it.
`RATE_LIMIT`	429	The account-wide API budget ran out, or the IP sent too many invalid credentials.
`RATE_LIMITED`	429	This route’s own limit was reached. Wait and retry.

Objects

Code	HTTP	Meaning
`INVALID_OBJECT`	400	The object id is malformed or not yours.
`INVALID_OBJECT_NAME`	400	`name` does not match the allowed pattern (1 to 128 characters).
`INVALID_OBJECT_PREFIX`	400	`prefix` does not match the allowed pattern.
`INVALID_OBJECT_EXPIRE`	400	`expire` is not a valid duration (1 hour to 1825 days).
`INVALID_OBJECT_PRIVATE`	400	`private` is not `true` or `false`.
`INVALID_OBJECT_SECURITY_HASH`	400	`security_hash` is not a boolean, or is `false` on a private object.
`INVALID_OBJECT_OVERWRITE`	400	`overwrite` is not `true` or `false`.
`INVALID_OBJECT_DISPOSITION`	400	`disposition` is not `inline` or `attachment`.
`INVALID_OBJECT_CACHE_CONTROL`	400	`cache_control` is not `immutable`, `no-cache` or `max-age=60..31536000`.
`INVALID_OBJECT_METADATA`	400	`metadata` is malformed, uses a reserved key, or passes 5 keys or 512 bytes.
`INVALID_STORAGE_AUTO_DOWNLOAD`	400	`auto_download` is not `true` or `false`.
`INVALID_CHECKSUM`	400	`checksum_sha256` is not 64 lowercase hex characters.
`CHECKSUM_MISMATCH`	400	The file does not match `checksum_sha256`. Nothing was stored.
`INVALID_DESTINATION`	400	The copy `destination` is malformed.
`SAME_OBJECT`	400	The copy source and destination are the same object.
`NOTHING_TO_UPDATE`	400	The request changes no field.
`INVALID_CONTINUATION_TOKEN`	400	The list `cursor` is malformed or no longer valid. Start again without a cursor.
`TOO_MANY_OBJECTS`	400	Too many objects in one request (100 to delete, 50 to update).
`PREFIX_NOT_ALLOWED`	403	The upload token is bound to another prefix.
`OBJECT_NOT_FOUND`	404	The object does not exist.
`OBJECT_ALREADY_EXISTS`	409	An object with this id exists and `overwrite` is `false`.
`OBJECT_IS_LEGACY`	per object	Returned in the `results` of Object Update. The object is a legacy file, stored before the September 2026 update, and must be moved with Object Copy (`move: true`) before its headers can change.
`VISIBILITY_CHANGE_FAILED`	per object	Returned in the `results` of Object Update: the object could not be made private and is still public. Retry.
`UPDATE_FAILED` / `COPY_FAILED` / `DELETE_FAILED`	500	The operation failed. Retry.

Uploads

Code	HTTP	Meaning
`INVALID_CONTENT_TYPE`	409	Object Post only accepts `multipart/form-data` with exactly one file.
`INVALID_FILE`	400	The file part is missing or unreadable.
`INVALID_FILE_TYPE`	400	The file extension is malformed or too long.
`BLOCKED_FILE_TYPE`	400	Executables and installers are not accepted.
`FILE_TYPE_NOT_ALLOWED`	400	The upload token or the prefix rule does not allow this extension.
`FILE_TOO_SMALL`	400	Files must have at least 512 bytes.
`FILE_TOO_LARGE`	413	Past 100 MB in one request (use chunked uploads), or past the size allowed by the plan, token or rule.
`STORAGE_QUOTA_EXCEEDED`	403	The account reached its included storage.
`TOO_MANY_CONCURRENT_UPLOADS`	429	4 uploads are already running on this account.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	Storage is temporarily unavailable. Retry.
`UPLOAD_FAILED`	500	The upload failed. Retry.

Chunked uploads

Code	HTTP	Meaning
`INVALID_UPLOAD_TOKEN`	400	The `upload` token is missing, malformed or not yours.
`INVALID_CHUNK_PART`	400	`part` is not an integer from 1 to 2048.
`EMPTY_CHUNK`	400	The part body is empty.
`CHUNK_TOO_LARGE`	413	A part has more than 32 MB.
`CHUNK_TOO_SMALL`	400	A part other than the last has less than 5 MB.
`NO_CHUNKS_UPLOADED`	400	Complete was called before any part was sent.
`TOO_MANY_OPEN_UPLOADS`	429	The account has 32 open uploads. Complete or abort one.
`TOO_MANY_CONCURRENT_CHUNKS`	429	6 parts are already in flight on this account.
`UPLOAD_NOT_FOUND`	404	The upload was completed, aborted or expired.

Temporary links and shares

Code	HTTP	Meaning
`INVALID_DOWNLOAD_EXPIRES`	400	`expires` is outside 60 to 86400 seconds.
`INVALID_FILENAME`	400	`filename` is empty after removing invalid characters.
`INVALID_EXPIRES_IN`	400	`expires_in` is outside the allowed range.
`INVALID_MAX_DOWNLOADS`	400	`max_downloads` is outside 1 to 10000.
`INVALID_PASSWORD`	400	The password must have 8 to 128 characters.
`INVALID_SHARE`	400	The share id is malformed.
`SHARE_NOT_FOUND`	404	The share does not exist or was already revoked.
`TOO_MANY_SHARES`	409	The account has 1000 active shares. Revoke some first.

Account settings and upload tokens

Code	HTTP	Meaning
`INVALID_BODY`	400	The body is missing or is not a JSON object.
`INVALID_RULES`	400	`rules` is not an array.
`TOO_MANY_RULES`	400	More than 20 rules on Enterprise. On other plans, passing the plan’s limit (5 on Hobby and Standard, 10 on Pro) answers `UPGRADE_REQUIRED`.
`INVALID_RULE_PREFIX` / `DUPLICATE_RULE_PREFIX`	400	A rule prefix is malformed, or repeats another rule’s.
`INVALID_RULE_PRIVATE` / `INVALID_RULE_EXPIRE` / `INVALID_RULE_MAX_SIZE` / `INVALID_RULE_EXTENSIONS` / `INVALID_RULE_CACHE_CONTROL` / `INVALID_RULE_DELETE_AFTER`	400	A rule field is invalid. The response carries the `prefix` of the rule.
`INVALID_EXPIRES_IN` / `INVALID_MAX_USES` / `INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS`	400	An upload token field is out of range.
`UPLOAD_TOKEN_TOO_LARGE`	400	The token options don’t fit in a token. Shorten metadata or the extension list.

S3 credentials

Code	HTTP	Meaning
`API_KEY_REQUIRED`	400	S3 credentials derive from an API key, not a dashboard session.
`LEGACY_API_KEY`	400	The API key uses the old format. Create a new key in your account settings.
`INVALID_CREDENTIAL`	401	The API key could not be verified.

The S3 gateway answers with standard S3 XML errors instead.

Global

Code	HTTP	Meaning
`ROUTE_NOT_FOUND` / `NOT_FOUND`	404	The route does not exist.
`INTERNAL_SERVER_ERROR`	500	Unexpected failure. Retry later.

Getting Started

Objects

Chunked Uploads

Account

Share Links

S3

Authentication and limits

Objects

Uploads

Chunked uploads

Temporary links and shares

Account settings and upload tokens

S3 credentials

Global

​Authentication and limits

​Objects

​Uploads

​Chunked uploads

​Temporary links and shares

​Account settings and upload tokens

​S3 credentials

​Global

Authentication and limits

Objects

Uploads

Chunked uploads

Temporary links and shares

Account settings and upload tokens

S3 credentials

Global