> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # Errors > Every error code the Blob Storage API returns, with its HTTP status and what to do about it. Every error has the same shape. `code` is stable and meant for your code; `message`, when present, is a human explanation and may change. ```json theme={null} { "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](/en/blob-reference/authentication#scopes). | | `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](/en/blob-reference/endpoint/update). The object is a legacy file, stored before the September 2026 update, and must be moved with [Object Copy](/en/blob-reference/endpoint/copy) (`move: true`) before its headers can change. | | `VISIBILITY_CHANGE_FAILED` | per object | Returned in the `results` of [Object Update](/en/blob-reference/endpoint/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](/en/blob-reference/endpoint/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](/en/blob-reference/s3-compatibility#errors) 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. |