# CloudDisk Error Codes

This page lists the error codes returned by the CloudDisk v3 API, what they mean, and how to handle them.

## Error Response Format

When a request fails with a business error, CloudDisk responds with HTTP status `499` and a JSON body like this:

```json
{
  "code": "e_clouddisk_s3_client_error",
  "message": "s3 client error",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "errors": [
    {
      "code": "NoSuchKey",
      "message": "operation error S3: GetObject, https response error StatusCode: 404, ... NoSuchKey: The specified key does not exist."
    }
  ]
}
```

- `code`: The error code. All CloudDisk error codes start with `e_clouddisk_`. Handle errors in your code by `code`, not by `message`.
- `message`: A short description of the error.
- `trace_id`: The trace ID of the request. The same value is returned in the `x-mo-trace-id` response header. Provide it when you contact support.
- `errors`: Optional. More details about the error. For errors from the underlying storage, it contains the original error code and message returned by the storage.

An unexpected error is returned with HTTP status `599` and the code `e_common_server_error`. If it keeps happening, contact support with the `trace_id`.

<div class="docs-note"><span class="docs-admonitions-text">note</span>

`304 Not Modified` is not an error. When you get an object with `If-None-Match` or `If-Modified-Since` and the object has not changed, CloudDisk returns HTTP status `304` with an empty body. Use the copy you have cached.

</div>

## Bucket Errors

| Error Code | Description | How to Handle |
| ---------- | ----------- | ------------- |
| `e_clouddisk_bucket_exists` | A bucket with the same name already exists. | Use another name. Bucket names starting with `public-` or `mo-` must be unique across all tenants. |
| `e_clouddisk_bucket_not_exist` | The bucket does not exist, or you have no access to it. Also returned when an object is accessed through a public URL but the bucket does not allow public access. | Check the bucket name and the tenant. Call *Query Buckets* to list the buckets you can access. |
| `e_clouddisk_bucket_invalid_name` | The bucket name does not satisfy the naming rules. | See [Naming a Bucket](./InsureMO_clouddisk_bucket.md#naming-a-bucket). |
| `e_clouddisk_bucket_invalid_secret` | The stored credential of the bucket cannot be read. | Update the bucket with the credential again. If the error persists, contact support. |
| `e_clouddisk_bucket_not_empty` | The bucket still contains objects and cannot be deleted. Returned only for *non-prod testing* and *Database* buckets. | Delete all objects in the bucket first, then delete the bucket. See [Delete a Bucket](https://docs.insuremo.com/common/doc_00000316#delete-a-bucket). |
| `e_clouddisk_bucket_test_not_ready` | The connectivity test failed when creating or updating a *non-prod testing* bucket. | Retry later. If the error persists, contact support with the `trace_id`. |
| `e_clouddisk_bucket_default_invalid` | The *non-prod testing* storage is not configured in the current environment. | Contact support. |

## Storage Type Errors

| Error Code | Description | How to Handle |
| ---------- | ----------- | ------------- |
| `e_clouddisk_source_invalid_type` | The storage type of the bucket is not supported, or not enabled in the current environment. | Check `source_type` of the bucket. See [Bucket Integrate with Cloud Storages](https://docs.insuremo.com/common/doc_00000316#bucket-integrate-with-cloud-storages) for the supported types. |
| `e_clouddisk_source_action_not_support` | The storage of the bucket does not support this action. | See [Supported Actions by Storage](https://docs.insuremo.com/common/doc_00000316#supported-actions-by-storage). Use a bucket on another storage if you need the action. |

## Object Errors

| Error Code | Description | How to Handle |
| ---------- | ----------- | ------------- |
| `e_clouddisk_object_not_exist` | The object does not exist. Returned only for *Database* buckets. For other storages, see [Storage Errors](#storage-errors). | Check the key and the version ID. Call *List Objects* or *Exist Object* to check the object. |
| `e_clouddisk_object_content_length_limit_exceeded` | The object is larger than the size limit of the bucket. *Database* buckets accept objects up to 10 MB. | Upload a smaller object, or use a bucket on another storage. |
| `e_clouddisk_object_invalid_range` | The `Range` header is invalid. | Use the format `bytes=start-end`, and make sure the range is within the object size. |

## Pre-signed URL Errors

These errors are returned when you call *Presign Object* or access an object through a pre-signed insureMO link. See [Share an Object](https://docs.insuremo.com/common/doc_00000318#share-an-object).

| Error Code | Description | How to Handle |
| ---------- | ----------- | ------------- |
| `e_clouddisk_object_presign_invalid_expires` | `expired_in_second` is larger than `604800` (7 days). | Set `expired_in_second` to `604800` or less. |
| `e_clouddisk_object_presign_invalid_method` | A pre-signed URL for a method other than `GET` was requested, but only an insureMO link is available for the bucket, which supports `GET` only. | Pre-sign with `GET`, or use a bucket whose storage supports native pre-signed URLs. |
| `e_clouddisk_object_presign_expired` | The pre-signed URL has expired. | Call *Presign Object* again to get a new URL. |
| `e_clouddisk_object_presign_signature_not_match` | The signature of the pre-signed URL is invalid, usually because the URL was modified or truncated. | Use the URL exactly as returned. Do not modify or re-encode its query parameters. |
| `e_clouddisk_object_presign_invalid_params` | The query parameters of the pre-signed URL are incomplete or malformed. | Use the URL exactly as returned, including all of its query parameters. |

## Storage Errors

When the underlying storage rejects a request, CloudDisk returns one of the error codes below. The `errors` field of the response contains the original error code and message from the storage. Check it to find the actual reason, for example `NoSuchKey` (object not found), `AccessDenied` (no permission), or `InvalidAccessKeyId` (wrong credential).

| Error Code | Storage | How to Handle |
| ---------- | ------- | ------------- |
| `e_clouddisk_s3_client_error` | AWS S3 or S3-compatible storage | The request was rejected by S3. Check the original error in `errors`. Common reasons: object not found, wrong credential or role, missing permission, or wrong region/endpoint. |
| `e_clouddisk_s3_server_error` | AWS S3 or S3-compatible storage | S3 failed to process the request. Retry later. You can also set `aws_retry_max_attempts` of the bucket to retry automatically. |
| `e_clouddisk_s3_unknown_error` | AWS S3 or S3-compatible storage | Check the original error in `errors`. If the error persists, contact support. |
| `e_clouddisk_oss_client_error` | Alibaba Cloud OSS | Check the original error in `errors`. |
| `e_clouddisk_azblob_client_error` | Azure Blob Storage | Check the original error in `errors`. |
| `e_clouddisk_msgraph_client_error` | Microsoft Graph (OneDrive/SharePoint) | Check the original error in `errors`. Its code is the HTTP status from Microsoft Graph, such as `http_404` (item not found) or `http_403` (no permission). |
| `e_clouddisk_sftp_client_error` | SFTP | Check the original error in `errors`. Common reasons: server unreachable, authentication failed, path not found, or no permission. |
| `e_clouddisk_database_error` | Database | Retry later. If the error persists, contact support with the `trace_id`. |

## Troubleshooting by Operation

| Operation | Common Error Codes |
| --------- | ------------------ |
| Create a bucket | `bucket_exists`, `bucket_invalid_name`, `source_invalid_type`, `bucket_test_not_ready` |
| Update a bucket | `bucket_not_exist`, `bucket_invalid_secret`, `bucket_test_not_ready` |
| Delete a bucket | `bucket_not_exist`, `bucket_not_empty` |
| Upload an object | `object_content_length_limit_exceeded`, `source_action_not_support`, storage errors |
| Download an object | `bucket_not_exist`, `object_not_exist`, `object_invalid_range`, storage errors |
| Share an object | `object_presign_invalid_expires`, `object_presign_invalid_method` |
| Open a pre-signed URL | `object_presign_expired`, `object_presign_signature_not_match`, `object_presign_invalid_params`, `bucket_not_exist` |

All codes in this table omit the `e_clouddisk_` prefix.