错误 | Glac 文档

所有错误的格式、docs_url 指向哪里，以及遇到把你带到这里的拒绝（套餐上限、项目的云盘和存储卷、账户被冻结、用户被锁定）、其他各种达到限制的情况、平台机器已满、离线或无法执行，以及另外几个与费用有关的错误时，该怎么办。

所有错误都是同一种格式：

{"error": {"type": "forbidden", "code": "plan_cap_reached", "message": "…", "param": "vcpus",
           "retryable": false, "request_id": "req-…", "docs_url": "https://glac.ai/docs/errors/#plan_cap_reached"}}

code 给程序看，说明是哪种失败；message 给人看，说明限制是多少、怎样解除；param 指明出问题的字段或限制；retryable: true 表示同一个调用稍后可能成功，知道何时可以重试时会带上 Retry-After；request_id 是这次调用的 ID，也在它的 X-Request-Id 中。

错误带有 docs_url 时，它指向本页上对应的错误码。下面这些错误码各有一节：错误信息把你带到本页的拒绝、所有达到限制的拒绝（套餐的、项目的或平台的限制）、源于平台机器的错误（已满、离线、易手，或无法执行请求）、访问沙箱或应用地址的访客可能遇到的一种错误，以及另外几个与费用有关的错误。其他错误码都在 API 参考中各个返回它的调用下说明。每项限制的具体数字见限制页面，可以应单个账户的要求提高的限制见提高限制。

`plan_cap_reached`

403：这次调用会让账户超出套餐允许同时拥有的数量，或超出允许的创建速度。param 指明是哪项限制：instances、vcpus 或 memory_bytes（账户所有项目中运行着的）、sleeping（保持休眠的沙箱）、app_instances（一个应用在一个区域中的实例）、creates_per_minute、creates_per_hour_per_project 或 app_creates_per_hour。错误信息会说明限制是多少、它是套餐的限制还是为该账户单独设置的、已用了多少，以及这次调用会增加多少。

会拒绝什么：创建沙箱、一次性运行、分叉和键控实例；会唤醒休眠沙箱的调用（命令、文件、重启、快照、恢复）；scale 要求的实例数超出套餐允许数量的应用；超出每小时限额的方块和版本。会唤醒沙箱的请求，无论是发到沙箱链接还是键控实例的地址，都会被它的机器以同样的方式拒绝，什么也不会被唤醒（每台机器只在自己分到的那部分账户额度内唤醒：账户在别的机器上还有余量时，某台机器可能会拒绝几秒钟，错误信息会说明这一点）；发往应用的请求如果需要唤醒或创建一个账户已没有余量容纳的实例，也会立即被拒绝，param 和措辞相同。让沙箱休眠和删除从不会被拒绝。
怎么办：让部分资源休眠，或删除一些；如果是三种速率限制，就等一等：它们可重试 (retryable)，并带有 Retry-After。在免费版上，可以换到限制更宽的付费版 (glac billing plan paid)。也可以请我们为账户提高限制：参见提高限制。GET /v1/account (caps) 会列出每项限制和当前用量。

各套餐的具体数字见限制页面。

`volume_limit_reached`

403：存储卷的数量超出了账户套餐允许一个项目拥有的数量，单个存储卷超出了允许的大小，或所有存储卷加起来超出了允许的总量（后两种情况的 param 为 size_bytes）。错误信息会给出套餐的数字、项目现有的情况和解决办法：删除一个存储卷、改用更小的存储卷，或换到能保留更多的付费版。在付费版上，存储卷数量是软限制，可以应要求提高；企业账户的存储卷还可以超过任何套餐的上限，最大 16 TiB。参见提高限制。

`drive_limit_reached`

403：与上一条相同，针对云盘：新建的云盘、分叉出的云盘，或从带有云盘的快照创建沙箱时随之得到的云盘，会让项目超出套餐允许拥有的云盘（数量、单个大小或总大小）。错误信息会给出套餐的数字、项目现有的情况、这次调用要创建的内容，以及和存储卷一样的解决办法：在付费版上，云盘数量可以应要求提高；企业账户的云盘最大可到 16 TiB。云盘的快照不计入。参见各套餐的数字和提高限制。

`spend_limit_reached`

403：达到了支出上限，可能是项目的，也可能是某个沙箱自己的（PATCH /v1/limits、PATCH /v1/sandboxes/{id}/limits）；错误信息会说明是哪一个，以及怎样解除。达到上限的项目中不能新建任何东西（沙箱、存储卷、云盘、快照、应用的版本都不行），被上限冻结的沙箱不会被唤醒。经由沙箱链接或应用地址、发往已冻结或已停止的沙箱或应用的请求，也会以这个错误码响应，无论它是因为什么停止的。

怎么办：提高上限，或去掉上限 (null)，之后被冻结的东西会被下一个需要它的调用唤醒。当月的支出从下个月起重新计算。参见支出上限。

`quota_used_up`

429，免费版：这次调用要用的计量项，今天 (UTC) 的配额已经用完。用完的是哪一项，决定了什么会停止，与账户里有多少余额无关：

CPU 时间或内存：账户的沙箱连同数据一起休眠，项目中不能再新建任何东西，会唤醒沙箱的调用都会被拒绝；
请求：发往账户沙箱和应用的请求，边缘节点都以这个错误码响应；
发往互联网的流量：沙箱发往互联网的流量停止；
日志：应用输出的内容不再保留。

可重试 (retryable)，Retry-After 是距离 00:00 UTC 的秒数。到那时配额全部重置，停下的东西会自动继续。免费版从不扣费：账户里的点数在免费版上不能用来支付任何费用。GET /v1/billing 会给出今天每项配额的用量 (meters)，以及哪些计量项已停止 (meters.*.stopped)。

怎么办：等到 00:00 UTC，或换到付费版（glac billing plan paid，或调用 PATCH /v1/billing，plan 设为 paid）。付费版没有每日配额：每月包含每个计量项的一定用量，超出部分从余额中支付。参见计量项用完时。

`storage_quota_reached`

403，param 为 storage，免费版：账户保存的数据已达到免费版的上限：15 GB 的存储卷数据（存储卷中的数据，加上快照和休眠沙箱保存的内容），或 15 GB 的 NVMe 缓存。这是存量上限，不是每日配额。新建存储卷或快照会被拒绝；已保存的内容照常保留，不会停止，也不会被删除。存量按最近一个完整小时的账目计算。

怎么办：删除不需要的内容，账户保存的数据降下来后就能再新建；或者换到付费版：每月包含一定的数据量，超出部分按价格计费。GET /v1/billing 会显示当前保存了多少（meters.volume_data、meters.volume_cache）。

`balance_used_up`

403，付费版：本期包含的 CPU 时间或内存已经用完，账户也没有余额来支付超出的部分。账户的沙箱被冻结，项目中不能新建任何东西（应用的新版本也不行），会唤醒被冻结沙箱的调用都会被拒绝。

怎么办：给余额充值（POST /v1/billing/topups，或控制台的计费页面），或开启自动充值。否则这种状态会持续到下一个周期开始。GET /v1/billing 会给出哪个计量项已停止 (meters.*.stopped)，以及下一个周期何时开始。在免费版上，每日配额用完返回的则是 429 quota_used_up。参见计量项用完时。

`needs_balance`

403，param 为 egress_overage：免费版账户，或余额为零的账户，调用 PATCH /v1/account 并设置 egress_overage: pay。超出付费版包含额度的互联网流量，只能由付费版账户用余额支付。不会做任何更改：超出套餐的包含额度后，流量照常停止。GET /v1/billing 会显示套餐、余额和每个计量项的用量。

怎么办：换到付费版（调用 PATCH /v1/billing，plan 设为 paid），并给余额充值（POST /v1/billing/topups，或控制台的计费页面）。有余额的付费版账户会自动支付超出包含额度的流量，此时 egress_overage 显示为 pay；egress_overage_cap_bytes 可以为这部分设置上限。参见余额。

`plan_limit_reached`

403，返回给经由沙箱链接、应用地址或域名发来的请求：账户发往互联网的流量已停止（付费版：本期包含的流量已经发完，且没有余额支付更多；或者达到了账户自己设置的每月上限），或者（仅边缘节点会返回）本期包含的请求数已经用完，且没有余额。由边缘节点或机器直接响应，所有者的程序都还没有运行。免费版每日配额用完导致的停止，返回的则是 429 quota_used_up。

怎么办：与 balance_used_up 相同：充值，或等待下一个周期。账户自己设置的上限，用 PATCH /v1/account (egress_overage_cap_bytes) 提高；不提高的话，会持续到下一个自然月。参见计量项用完时。

`plan_size_exceeded`

403：沙箱会超出账户套餐允许的单个沙箱规格。超出的可能是请求的 limits（param 为 limits.vcpus、limits.memory_bytes，两者都超出时为 limits），也可能是来源的规格，即创建、分叉或回退时所基于的快照、模板或沙箱。不指定规格的沙箱从不会因此被拒绝：它最多按套餐允许的最大规格创建。账户回到免费版后（订阅已结束），超出免费版规格的沙箱会连同数据一起休眠，直到账户换回付费版才会被唤醒；沙箱的任何内容都不会被删除或缩小。

怎么办：改用更小的规格，或换到付费版，它允许的最大沙箱更大（调用 PATCH /v1/billing，plan 设为 paid）。各套餐的最大规格见限制页面。

`paid_plan_required`

403，param 为对应的字段：调用要求的功能只有付费版提供，而账户在免费版上。这样的功能有：数据库的分层存储 (tiering.enabled)。不会做任何更改。GET /v1/billing 会显示账户当前的套餐。

怎么办：换到付费版（调用 PATCH /v1/billing，plan 设为 paid；或使用控制台的 Billing 页面），然后重新调用。

`proxy_not_on_plan`

403，param 为 proxy：在免费版上为浏览器会话设置了自己的代理，而免费版不提供这项功能。不会创建或修改任何东西。

怎么办：创建会话时不带 proxy，或换到付费版（调用 PATCH /v1/billing，plan 设为 paid）。GET /v1/billing 会显示账户当前的套餐。

`secret_limit_reached`

403：机密的数量超出了账户套餐允许一个项目拥有的数量（修改项目已有的机密不受数量限制），单个机密的值超出了允许的大小（param 为 value），或者会让应用的实例拿到的项目机密超出单个沙箱允许的数量（错误信息会指明是哪个应用）。错误信息会给出套餐的数字。

怎么办：删除项目不再需要的机密 (DELETE /v1/secrets/{name})，改用更小的值，或换到能保有更多的套餐。参见各套餐的数字。

`app_limit_reached`

403：账户在所有项目中的应用数量已达到套餐允许的上限。等待不会改变什么。

怎么办：删除不再需要的应用 (DELETE /v1/apps/{app})，或换到允许更多应用的付费版。参见各套餐的数字。

`env_limit_reached`

403：应用的环境变量和机密合计会超出账户套餐允许单个应用拥有的数量。

怎么办：减少应用的环境变量和机密（多个应用都要读取的内容可以放在共享变量 /v1/variables 中），或换到允许单个应用拥有更多的套餐。参见各套餐的数字。

`key_secret_limit_reached`

403，来自 POST /v1/apps/{app}/key-secrets：应用已有两个用来签名键的机密，这是上限。

怎么办：先删除已不再用于签名键的那个机密 (DELETE /v1/apps/{app}/key-secrets/{secret})。参见键控实例。

`domain_limit_reached`

403：项目的自定义域名已达到单个项目的上限 (100)。

怎么办：删除不再使用的域名。参见 API 的限制。

`variable_limit_reached`

403：项目的共享变量已达到单个项目的上限 (1,000)。

怎么办：删除不再使用的变量。参见 API 的限制。

`destination_limit_reached`

403：账户在所有项目中的应用日志导出目标已达到套餐允许的上限。

怎么办：删除不再导出日志的目标，或换到允许更多导出目标的套餐。参见各套餐的数字。

`account_share_reached`

403：账户新建的东西（沙箱、一次性运行、分叉的副本、快照、存储卷或云盘）会让它超出所在机器数据盘上的份额：一个账户最多占用一台机器磁盘的一定份额，除非机器另有设置，否则为四分之一，账户在那里的所有东西都计算在内。平台会把新建的东西放到账户还有空间的机器上，哪台都没有时才返回这个错误。错误信息会说明账户在那里已占用多少、最多能占用多少，以及这次需要多少。

怎么办：删除账户不再需要的东西（休眠的沙箱、快照、云盘），或者稍后重新创建，那时可能会找到有空间的机器。机器的份额不会为单个账户提高。

`app_rate_limited`

429，带 Retry-After: 1：应用在这个边缘节点上每秒收到的请求数，已达到账户套餐给单个应用的上限（这是免费版的限制，付费版没有）。请求没有到达任何机器，没有唤醒或创建任何东西，也不计数、不计费。

怎么办：一秒后重新发送，或换到付费版。参见各套餐的数字。

`too_many_followers`

429，可重试 (retryable)：同时跟随账户应用日志的读取方，已达到套餐允许的数量（GET /v1/account 中的 logs.followers）。

怎么办：结束一个正在跟随的读取方（一直开着的 glac cube logs -f、页面上的日志流），或稍后再试。参见各套餐的数字。

`egress_connections_full`

503，可重试 (retryable)，针对沙箱自己的出站连接：账户在这台机器上的沙箱经由其出站代理同时建立的连接，已达到账户份额允许的总数。普通 HTTP 连接会收到这个响应；TLS 连接以告警结束，其他连接会被重置。其他账户的连接不受影响。

怎么办：关闭不用的连接，或减少同时打开的连接；稍后再试。参见出站连接。

`too_many_drives`

409：沙箱自己的云盘和存储卷会超过 8 个，这是单个沙箱的上限。

怎么办：给沙箱少挂几个，或者把几个云盘的数据合到一个云盘中。参见云盘的限制。

`too_many_volumes`

409，param 为 volumes：沙箱自己的（非共享）存储卷会超出它的机器可用的空闲磁盘数：8 个，这是单个沙箱的上限；从支持 8 个之前的模板或快照创建的沙箱为 2 个，直到它下一次从磁盘启动。共享存储卷不计数。GET /v1/sandboxes/{id} 会列出沙箱拥有的存储卷。

怎么办：给沙箱少挂几个，把几个存储卷的数据合到一个中，或者改用共享存储卷（共享存储卷不计数）。这是平台的限制，所有套餐都一样。

`too_many_projects`

409，来自 POST /v1/accounts/{id}/projects：账户已有 100 个项目，这是单个账户的上限。

怎么办：删除不再使用的项目。

`too_many_free_accounts`

409，来自 POST /v1/me/accounts：用户拥有的免费版账户数量已达到单个用户的上限。

怎么办：把本打算放进新账户的项目建在用户已有的账户中，或者把其中一个免费版账户换到付费版。

`too_many_revoked_tokens`

409：要单独吊销沙箱的某个令牌，而沙箱已逐个吊销、尚未过期的令牌已达到上限（1,000；param 为 token）。

怎么办：一次吊销沙箱的所有令牌（不带请求体的 POST /v1/sandboxes/{id}/tokens/revoke），之后再签发新令牌。参见单个令牌。

`too_many_ssh_keys`

409，来自 POST /v1/ssh-keys：项目已注册 1,000 个 SSH 密钥，这是单个项目的上限。GET /v1/ssh-keys 会列出它们。

怎么办：删除不再使用的密钥（DELETE /v1/ssh-keys/{id}、glac sandboxes ssh-keys rm）。参见 SSH。

`too_many_forwards`

503，可重试 (retryable)：沙箱从 SSH 网关同时打开的连接已达到单个沙箱的上限（SSH 会话的端口转发和 agent 合计 64 个，机器另有设置时除外），新连接会被拒绝。已打开的连接不受影响。

怎么办：关闭不用的转发，或者等其中一个结束后再试。参见 SSH。

`rate_limited`

429，可重试 (retryable)，带 Retry-After：登录、注册、通过邮件重设密码、验证地址的邮件或邀请，暂时尝试次数过多：可能是同一个地址、同一个来源、同一个用户或同一个账户。这次尝试不算数，拒绝信息也不会透露这个地址是否有用户。

怎么办：等 Retry-After 之后再试。

`report_in_progress`

429，可重试 (retryable)，来自 GET /v1/usage：同一个项目的另一份用量报告 2 秒后仍在生成。一个项目的报告一次只生成一份。

怎么办：等另一份报告返回后再请求。

`too_many_connections`

429，带 Retry-After: 1，来自边缘节点：它承载的来自客户端地址的同时请求数，已达到单个地址的上限。所有者的任何程序都没有运行。

怎么办：一秒后再发送，或者减少从同一个地址同时打开的连接。

`body_too_large`

413：请求体超出了这个调用接受的大小；错误信息会说明上限。连接会被关闭。文件内容不受此限：参见 API 的限制。

怎么办：每次调用少发一些：命令的输入分段发送 (…/exec/{exec_id}/stdin)，文件通过文件相关的调用发送。

`no_capacity`

503，可重试 (retryable)：此刻没有机器能承接这个调用要创建的东西，什么都没有创建。错误信息会说明原因：没有机器有空间（现有的都满了，或暂时不再分配新东西）；没有机器的磁盘有空间构建镜像；被询问的机器都拉取不到镜像（param 为 image）；拥有它的来源、或能从对象存储获取来源的机器都不在；或者，从备份创建存储卷时，备份所在区域没有会复制到对象存储的机器。这是一时的拒绝，与你的套餐无关：套餐的限制是配额，不是预留（限制）。

哪些调用会返回它：主要是创建东西的调用：沙箱、一次性运行、分叉、键控实例、存储卷或云盘。
怎么办：稍后再调用。SDK 会按 retries 的设置自动重试几次，然后才抛出异常。

`strict_unsupported`

409：在无法保证 strict 的地方使用 strict 云盘：在不向对象存储复制任何数据的机器上，或挂载在从支持 strict 云盘之前的模板创建的沙箱中，它的机器无法把客户机的刷写传递下去。什么都没有创建或挂载。请把它挂载到从较新模板（现在创建的）创建的沙箱中，或者把云盘设为 standard。

`standby`

503，可重试 (retryable)，带 Retry-After：调用到达了控制平面中没有在提供服务的那个副本。控制平面在两个站点各运行一个副本；一个副本从另一个接手期间（站点丢失、升级），调用会收到这个响应，如果这个副本知道哪个副本在提供服务，active 会指明它。什么都没有做。等 Retry-After 之后再调用：SDK 会按 retries 的次数自动重试。参见机器丢失时。

`fenced`

503，可重试 (retryable)：持有沙箱的机器与控制平面失联的时间已超过它的租约，它无法确定沙箱是否仍归它：沙箱可能已在另一台机器上被接管。在控制平面答复之前，它不会为这个沙箱启动任何东西，也不会响应与它有关的任何请求；调用已为此先等待了三秒。请再次调用：控制平面答复之后，调用会被送到沙箱所在的地方。参见机器丢失时。

`checkpoints_unavailable`

409，param 为 checkpoint：在没有机器能创建检查点的情况下请求了检查点：平台上没有既把磁盘复制到对象存储、又把内存分层保存的机器，或者沙箱的来源在不支持的机器上，或者用 PATCH 为这类机器上的沙箱开启检查点。什么都没有创建或修改。请不带 checkpoint 创建沙箱，或者从支持检查点的机器能获取的来源创建。所有这类机器都离线或已满时，同一个调用会改为返回 503 no_capacity。

`malformed_answer`

502，不可重试（非 retryable）：访问沙箱链接或应用地址的访客，会在两种情况下从前面的机器收到这个响应。第一种：沙箱中服务的响应在长度上自相矛盾（同时有 Transfer-Encoding 和 Content-Length，或者 Content-Length 不是数字或有两个值），这个响应的任何内容都不会被传出。第二种：服务接收了请求，却没有任何响应就关闭了连接，比如沙箱的内核因内存耗尽结束了进程。平台不会重发请求，因为服务可能已经处理过它。

怎么办：第一种情况，修正服务的响应：两个长度字段只用一个，不要同时使用。第二种情况，查清进程为什么停止：看运行服务的那条命令的输出 (glac sandboxes logs)，以及沙箱的内存和设置 (glac sandboxes get)。只有在重复执行无害时，才重新发送请求。

`account_held`

403：账户因付款问题被冻结，直到支持团队处理完毕。在此期间：

用该账户项目的密钥和沙箱的令牌发起的调用都会被拒绝，GET /v1/account 除外，它的 payment_hold 说明从何时开始冻结；
账户的沙箱连同数据一起休眠，发往它的应用和沙箱的请求会被拒绝；进行中的部署会失败，流量留在原来的版本上；
不会向它收取任何费用，它的任何东西也不会被删除。

账户被冻结时会收到一封邮件（account_held 通知）。API 和邮件都不会说明原因：请带上账户 id 发邮件到 support@glac.ai，请求处理。

`account_in_debt`

402：账户欠费。超出套餐所含存储量的保存内容（休眠沙箱、快照、存储卷和云盘）要从余额中支付，余额不足，已经变成负数，欠款达到 $0.50 或以上。在付清之前：

用该账户项目的密钥和沙箱的令牌发起的调用都会这样被拒绝，但查看欠款的调用（GET /v1/account、GET /v1/usage、GET /v1/events、/v1/billing 下的读取）、付款的调用，以及删除所存内容的调用除外；
账户的沙箱连同数据一起休眠，发往它的应用和沙箱的请求会被拒绝。

欠款开始时账户会收到邮件，之后还会收到提醒；第一封邮件发出三十天后，它存储的内容会被删除，欠款随之核销。

怎么办：付清欠款：一次让余额回到零或以上的充值（POST /v1/billing/topups，或控制台的 Billing 页面）会立即结束欠费状态。GET /v1/billing 会显示余额。参见欠费的账户。

`user_locked`

403：用户已被锁定。登录控制台（无论用密码、GitHub 还是 Google），以及用于设置新密码的链接，都会被拒绝（只有密码正确时，登录才会得知这一点）。请用该用户的邮箱发邮件到 support@glac.ai。

`billing_address_required`

409，param 为 billing_address：无人在场时对银行卡的扣款（通过 API 充值、付费版的月费、开启自动充值）需要知道账户所在地才能计税，而账户没有账单地址，银行卡也没有注明国家。不会扣任何款。请设置账单地址（glac account billing-address --country DE，或调用 PATCH /v1/account 并带上 billing_address），或者在付款页面 (POST /v1/billing/checkout) 付款，那里会询问地址。控制台的 Billing 页面会先询问地址，再更换银行卡。

`trust_limit_exceeded`

403：充值、自动充值或支出上限超出了账户的信任等级本月允许扣款的金额。错误信息会说明等级、本月已用多少，以及等级何时自动提升。支持团队可以应要求提升等级：参见信任等级和提高限制。