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

# 创建 snapshot

> 对你的数据库执行 snapshot。速率限制为每 5 秒 1 次请求。

<Warning>每个账户每 24 小时最多可执行 (RAM / 256) \* 2 次 snapshot。</Warning>

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  你账户的 API 密钥。你可以在[账户设置](https://squarecloud.app/zh/account/security)中找到它。
</ParamField>

### 参数

<ParamField path="database_id" type="string" placeholder="Database ID" required>
  数据库的 ID。
</ParamField>

### 软截止时间行为

此路由遵循**软截止时间**模型 — 它不再总是同步响应。

* 如果 snapshot 在 **\~90 秒**内完成，该路由将返回 `200 success` 以及一个已签名的下载 URL（有效期 30 天），与之前完全相同。
* 如果 snapshot 生成时间超过 **\~90 秒**，该路由将**立即**返回 `202` 以及代码 `SNAPSHOT_PROCESSING`。**这不是失败。** snapshot 会在后台继续生成，并会自行出现在 [snapshot 列表](/zh/api-reference/endpoint/databases/snapshots/list)中，通常在 \~2 分钟内。对于大型数据库来说这是预期行为。

<Warning>
  请勿将此 `POST` 端点用作轮询机制。要检查处于 `SNAPSHOT_PROCESSING` 状态的 snapshot 是否已完成，请使用 [List Snapshots](/zh/api-reference/endpoint/databases/snapshots/list)（`GET`）端点 — **而不是**另一个 `POST`。在 snapshot 完成后重新发起 `POST` 会从头开始一个全新的 snapshot。
</Warning>

客户端应根据响应进行如下分支处理：

| 响应                                                      | 含义              | 应执行的操作                                                                                                         |
| ------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------- |
| `status === "success"`                                  | snapshot 已就绪。   | 使用 `url` 下载它。                                                                                                  |
| `status === "error"` 且 `code === "SNAPSHOT_PROCESSING"` | snapshot 仍在生成中。 | 等待 \~2 分钟，然后通过 [List Snapshots](/zh/api-reference/endpoint/databases/snapshots/list)（`GET`）确认。**请勿**重新 `POST`。 |
| `status === "error"` 且带有任何其他 `code`                     | 实际失败。           | 处理该错误（见下文）。                                                                                                    |

### 响应

<ResponseField name="status" type="string">
  指示调用是否成功。成功时为 `success`，否则为 `error`。
</ResponseField>

<ResponseField name="response" type="object">
  响应的内容。仅当 `status` 为 `success` 时存在。

  <Expandable title="切换对象">
    <ResponseField name="url" type="string">
      用于下载应用程序 snapshot 的 URL。
    </ResponseField>

    <ResponseField name="key" type="string">
      用于下载应用程序 snapshot 的密钥。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="SNAPSHOT_PROCESSING" type="202">
  当 snapshot 超过 \~90 秒的软截止时间时返回。snapshot 仍在后台生成，并会自行出现在 snapshot 列表中，通常在 \~2 分钟内。这不是错误 — 请等待并通过 `GET` 列表端点确认。
</ResponseField>

### 错误

snapshot 请求可能会被拒绝并返回 `429 Too Many Requests`。使用 `code` 字段来区分这两种情况：

<ResponseField name="KEEP_CALM" type="429">
  短期冷却 — 你触发了每用户（每 5 秒 1 次请求）或每数据库（每 180 秒 1 次请求）的限制。请退避并稍后重试。
</ResponseField>

<ResponseField name="DAILY_SNAPSHOTS_LIMIT_REACHED" type="429">
  已达到每日配额 — 该账户已用完其套餐的每日 snapshot 额度（每 24 小时 (RAM / 256) × 2 次）。随着滚动的 24 小时窗口推进，配额会释放；如需更高的每日额度，请升级套餐。
</ResponseField>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "status":"success",
    "response":{
      "url":"https://snapshots.squarecloud.app/databases/384443501775028242/a14b8d5e1cb7405a851eb4c075506121.zip?AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%3D",
      "key":"AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%3D"
    }
  }
  ```

  ```json 202 SNAPSHOT_PROCESSING theme={null}
  {
    "status": "error",
    "code": "SNAPSHOT_PROCESSING"
  }
  ```

  ```json 429 KEEP_CALM theme={null}
  {
    "status": "error",
    "code": "KEEP_CALM",
    "message": "You already requested a snapshot recently. Please wait a minute before trying again. 1r/5s"
  }
  ```

  ```json 429 DAILY_SNAPSHOTS_LIMIT_REACHED theme={null}
  {
    "status": "error",
    "code": "DAILY_SNAPSHOTS_LIMIT_REACHED",
    "message": "You are being rate limited for daily snapshots. 8r/24h"
  }
  ```
</ResponseExample>