> ## 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.

# Blob Storage API error codes

> Every error code the Blob Storage API returns, with its HTTP status and what to do about it, plus when to retry with backoff and when to fix the request.

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={"system"}
{
    "status": "error",
    "code": "UPGRADE_REQUIRED",
    "message": "Custom metadata is available on Pro and Enterprise plans only."
}
```

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

## 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 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_LIMITED` | 429 | This route's own limit or the account-wide API budget was reached, or the IP sent too many invalid credentials. 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.