# 错误码

API Key 可能收到的每个错误码，及其 HTTP 状态码、remediation.action、含义和 Retry-After。

这张表从 OpenAPI 规格生成。错误信封的结构、重试策略和限流规则见 [API 约定](https://mirabase.io/zh/developers/conventions.md#errors)。按 `code` 和 `remediation.action` 分支处理；没有 `remediation.action` 的错误码没有固定的下一步，按 HTTP 状态码处理。后续可能新增错误码，未知错误码同样按 HTTP 状态码处理。

## 错误码

| 错误码 | 状态 | `remediation.action` | 含义 |
| --- | --- | --- | --- |
| `validation_error` | 400 / 422 | `fix_request` | 请求不合法。 |
| `invalid_request` | 400 / 422 | `fix_request` | 请求不合法。 |
| `unsupported_contract_version` | 400 | `drop_contract_version` | 服务不支持这个 `Mirabase-Contract-Version` 值：去掉这个请求头。 |
| `unauthorized` | 401 | `check_api_key` | Key 缺失、无效、已过期或已吊销。 |
| `account_pending_approval` | 403 | `wait_for_approval` | 账户尚未通过审批。审批通过后，用原来的 Key 重试。 |
| `account_rejected` | 403 | `contact_support` | 账户未通过审批。请通过联系页咨询。 |
| `account_suspended` | 403 | `contact_support` | 账户已停用。请通过联系页咨询。 |
| `forbidden` | 403 | `check_permissions` | 能力或角色不足。 |
| `identity_override` | 403 | `remove_identity_fields` | 请求里出现了 `principal_id` 这类由服务端控制的字段。 |
| `proposal_required` | 403 | `request_direct_write_mode` | Agent 修改他人的文件，需要 `write_mode: direct`。 |
| `reserved_path` | 403 | `choose_another_path` | 路径在 `/.mirabase/` 下。 |
| `outside_write_root` | 403 | `ask_owner_to_change_write_root` | 写入落在成员的写入根路径之外。 |
| `outside_read_root` | 403 | `ask_owner_to_change_read_root` | 有读取根路径的成员使用了分支。 |
| `outside_metadata_scope` | 403 | `omit_scope_metadata_keys` | 带元数据范围的 Key 在范围的键上写了其他值：去掉这个键，或使用范围内的第一个值。 |
| `scoped_key_route_unavailable` | 403 | `use_unscoped_key` | 带元数据范围的 Key 只能读取、检索、回答和导入：这个操作需要不带范围的 Key。 |
| `console_session_required` | 403 | `use_console` | 这个操作只接受控制台会话，不接受 API Key：请在控制台里完成。 |
| `not_found` | 404 | `check_identifier` | 不存在，或对你不可见。 |
| `content_not_ready` | 404 | `wait_and_retry` | 这个视图需等待处理完成。 |
| `branch_not_found` | 404 | `check_identifier` | 分支不存在。 |
| `checkpoint_not_found` | 404 | `check_identifier` | 检查点不存在。 |
| `object_not_found` | 404 | `check_identifier` | 分支对象不存在。 |
| `snapshot_not_found` | 404 | `check_identifier` | 快照不存在。 |
| `webhook_not_found` | 404 | `check_identifier` | Webhook 不存在。 |
| `upload_not_found` | 404 | `check_identifier` | 上传不存在。 |
| `virtual_file` | 405 | `use_memories_api` | `/.mirabase/memory/MEMORY.md` 和 `RECENT.md` 是只读视图。 |
| `request_timeout` | 408 | `retry_later` | 读取请求体超时。 |
| `conflict` | 409 | - | 请求与当前状态冲突。只有在 `Idempotency-Key` 被复用于不同输入时，`remediation.action` 才是 `use_new_idempotency_key`；其他冲突没有动作。 |
| `path_conflict` | 409 | `choose_another_path` | 目标路径已被占用。 |
| `not_a_directory` | 409 | `choose_another_path` | 路径中的某一段是文件。 |
| `move_into_descendant` | 409 | `choose_another_path` | 目录不能移动到自身内部。 |
| `copy_into_descendant` | 409 | `choose_another_path` | 目录不能复制到自身内部。 |
| `directory_not_empty` | 409 | `set_recursive` | 删除非空目录需要 `recursive: true`。 |
| `subtree_too_large` | 409 | `split_request` | 超过同步节点上限：拆分请求，或带 `Prefer: respond-async`。 |
| `directory_is_write_root` | 409 | `change_member_write_root` | 该目录是某个成员的写入根路径，或包含它。 |
| `directory_is_read_root` | 409 | `change_member_read_root` | 该目录是某个成员的读取根路径，或包含它。 |
| `content_url_unavailable` | 409 | `use_content_endpoint` | 服务端保存的小文本文件没有下载地址：用 `view=raw` 读取。 |
| `too_many_open_proposals` | 409 | `review_or_withdraw_proposals` | 这个 Agent 在该 Space 里已有 100 个打开的提案。 |
| `proposal_conflict` | 409 | `resubmit_proposal` | 提交提案后文件已变更或移入废纸篓：请重新提交。 |
| `proposal_closed` | 409 | `stop_retrying` | 提案或整理提案已不在打开状态。 |
| `memory_pending_review` | 409 | `review_memory_first` | 这条记忆正在等待审核：先审核，再修改。 |
| `memory_already_reviewed` | 409 | `stop_retrying` | 这条记忆已不在待审核状态。 |
| `memory_superseded` | 409 | `read_current_memory` | 这条记忆已被后来的修订取代：请读取当前的记忆。 |
| `undo_window_expired` | 409 | `stop_retrying` | 撤销只在 30 分钟内可用。 |
| `undo_not_applicable` | 409 | `undo_the_correction` | 提炼出的事实没有可撤销的写入：撤销取代它的那次更正。 |
| `upload_not_open` | 409 | `start_new_upload` | 上传已完成或已中止：请重新发起。 |
| `upload_conflict` | 409 | `start_new_upload` | 上传处于冲突状态：请重新发起。 |
| `snapshot_name_taken` | 409 | `choose_another_name` | 这个 Space 已有同名快照。 |
| `too_many_snapshots` | 409 | `delete_unused_snapshots` | 这个 Space 的快照数量已达上限。 |
| `snapshot_too_large` | 409 | `review_usage` | 超过快照的文件数上限。 |
| `too_many_webhooks` | 409 | `delete_unused_webhooks` | 这个 Space 的 Webhook 数量已达上限。 |
| `export_too_large` | 409 | `split_request` | 导出超过文件数或字节上限：按 `path` 分次导出。 |
| `artifact_not_ready` | 409 | `wait_for_job` | 导出尚未完成。 |
| `space_busy` | 409 | `wait_and_retry` | 这个 Space 持续繁忙了 2 秒。`Retry-After`：1 秒。 |
| `space_external_id_taken` | 409 | `find_space_by_external_id` | 账户里的另一个 Space 已使用这个 `external_id`。如果你能看到它，用 [`GET /v2/spaces?external_id=`](https://mirabase.io/zh/developers/api/spaces.md#spaces-list) 或 [`PUT /v2/spaces/ext:<external_id>`](https://mirabase.io/zh/developers/api/spaces.md#spaces-ensure) 获取；如果看不到，请换一个 id。 |
| `job_in_flight` | 409 | `wait_and_retry` | 有工作正在进行：等待 `job_id`。 |
| `evidence_changed` | 409 | `retry_request` | 构建结果期间证据发生了变化：请重新发送。 |
| `branch_not_active` | 409 | `open_new_branch` | 分支已合并或已放弃。 |
| `branch_name_taken` | 409 | `choose_another_name` | 已有同名的活跃分支。 |
| `branch_limit_reached` | 409 | `abandon_or_merge_branches` | 这个 Space 的活跃分支数量已达上限。 |
| `branch_too_large` | 409 | `merge_or_split_branch` | 分支的路径数量已达上限。 |
| `checkpoint_limit_reached` | 409 | `open_new_branch` | 分支的检查点数量已达上限。 |
| `merge_conflict` | 409 | `resolve_conflicts` | 主线修改了分支也修改过的路径：见 `conflicts`。 |
| `merge_too_large` | 409 | `split_request` | 一次合并超过 1000 个路径：用 `paths` 分批，或带 `Prefer: respond-async`。 |
| `merge_in_progress` | 409 | `wait_for_job` | 这个分支的合并任务正在排队或运行。 |
| `dream_run_in_flight` | 409 | `wait_for_job` | 这个范围的一次整理正在排队或运行。 |
| `dreaming_disabled` | 409 | `enable_memory_dreaming` | 这个 Space 的整理设置为 `off`。 |
| `api_key_not_live` | 409 | `issue_new_key` | Key 已吊销或已过期。 |
| `self_rotation_not_allowed` | 409 | `issue_new_key_then_revoke` | Key 不能轮换自己。 |
| `owner_membership_immutable` | 409 | `keep_owner_membership` | 所有者的成员关系不能修改。 |
| `default_space_protected` | 409 | `keep_default_space` | 默认 Space 不能删除。 |
| `tenant_deleted` | 409 | `stop_requests` | 账户已删除。 |
| `tenant_limit_reached` | 409 | `delete_unused_resources` | 账户的活跃 Key、主体或 Space 数量已达上限。 |
| `gone` | 410 | `stop_retrying` | 这张回执对应的 Entry 已被彻底删除。 |
| `cursor_expired` | 410 | `resync_from_tree` | 游标已超过 90 天：从 `tree` 重新同步。 |
| `artifact_expired` | 410 | `start_new_export` | 导出失败、已超过 7 天，或因彻底删除或读取根路径变化而失效。 |
| `export_invalidated` | 410 | `start_new_export` | 导出期间有内容被彻底删除，或读取范围发生了变化：请重新导出。 |
| `precondition_failed` | 412 | `reread_and_retry` | `If-Match` 或 `If-None-Match` 不满足。 |
| `payload_too_large` | 413 | `reduce_payload` | 请求体过大。 |
| `patch_base_too_large` | 413 | `use_put` | 文件超过 1 MiB，不能用 `PATCH`。 |
| `archive_too_large` | 413 | `split_archive` | 导入的归档过大，或包含超过 10,000 个条目。 |
| `upload_invalid` | 413 / 422 | `fix_request` | 上传请求不合法，或文件超过上限。 |
| `upload_media_type_mismatch` | 415 | `fix_request` | 上传内容的类型与发起时声明的不一致。 |
| `unsupported_media_type` | 415 | `use_put` | 不是 UTF-8 文本。 |
| `range_not_satisfiable` | 416 | `fix_request` | `Range` 超出文件范围。 |
| `invalid_path` | 422 | `fix_path` | 路径不符合规则。 |
| `path_too_long` | 422 | `shorten_path` | 路径超过长度上限。 |
| `edit_no_match` | 422 | `reread_and_retry` | 找不到 `old_text`。 |
| `edit_ambiguous` | 422 | `add_context_or_replace_all` | `old_text` 出现了不止一次。 |
| `view_not_available` | 422 | `choose_another_view` | 这个来源没有这种视图。 |
| `upload_expired` | 422 | `start_new_upload` | 上传会话已结束。 |
| `upload_size_mismatch` | 422 | `fix_request` | 上传的字节数与发起时声明的 `size` 不一致。 |
| `upload_integrity_mismatch` | 422 | `start_new_upload` | 上传的内容与 `checksum_sha256` 不符：请重新上传。 |
| `checksum_mismatch` | 422 | `fix_request` | 分支对象的哈希与它的 `sha256` 不符。 |
| `unknown_citation` | 422 | `use_citations_from_pack` | 反馈里的某个引用不在这个上下文包里。 |
| `write_root_outside_read_root` | 422 | `set_write_root_inside_read_root` | 写入根路径不在读取根路径之内。 |
| `invalid_webhook_url` | 422 | `fix_webhook_url` | Webhook 地址不是 443 端口上的公网 `https` 地址。 |
| `unsupported_archive` | 422 | `use_tar_archive` | 导入的不是 tar 或 gzip 压缩的 tar。 |
| `rate_limited` | 429 | `wait_and_retry` | 达到请求速率或并发上限。`Retry-After`：`limit` 为 `request_rate` 时，是请求令牌桶腾出空间所需的秒数；`limit` 为 `concurrency` 时为 1。 |
| `too_many_waiters` | 429 | `wait_and_retry` | 一个 Key 已保持 4 个长轮询。`Retry-After`：1 秒。 |
| `ingest_backlog` | 429 | `wait_and_retry` | 账户的排队任务过多：使内容可检索的任务超过 `tenant_queued_jobs`，或摘要、分类、关联和记忆任务超过它的五倍。`queue` 给出该类任务的数量、上限、处理是否已暂停，以及队列预计所需的时间。限定了部分 Space 或元数据范围的 Key 只会被告知已达上限。`Retry-After`：30 到 600：账户队列降到上限以下的预计时间；处理暂停期间为 600。对限定了部分 Space 或元数据范围的 Key 为 60。 |
| `too_many_jobs` | 429 | `wait_and_retry` | 这个 Space 已在运行 4 个改动目录树的任务，或 4 个导出。`Retry-After`：30 秒。 |
| `login_code_throttled` | 429 | `wait_and_retry` | 控制台邮箱验证码：请求过于频繁，或同一地址的错误验证码过多。`Retry-After`：验证码请求过于频繁时为 60；一小时内请求或错误验证码过多时为 3600。 |
| `quota_exceeded` | 429 | `review_usage` | 持久配额已用尽，或本次调用所需的量超过剩余额度，重试无效。`quota` 指明是哪一项：`writes`、`storage_bytes`、`model_tokens` 或 `model_spend_micro_usd`。 |
| `internal_error` | 500 | `retry_later` | 服务内部错误。 |
| `model_failed` | 502 | `retry_later` | 回答时模型调用失败。 |
| `original_unavailable` | 503 | `retry_later` | 原件暂时不可用。 |
| `answer_unavailable` | 503 | `retry_later` | 回答模型暂时不可用。 |
| `object_store_unavailable` | 503 | `retry_later` | 对象存储暂时不可用。 |
| `object_store_request_failed` | 503 | `retry_later` | 对象存储暂时不可用。 |
| `object_stream_integrity_mismatch` | 503 | `retry_later` | 对象存储暂时不可用。 |
| `spec_unavailable` | 503 | `feature_not_enabled` | 这个部署没有启用该功能，重试无效。 |
| `webhooks_unavailable` | 503 | `feature_not_enabled` | 这个部署没有启用该功能，重试无效。 |
| `answer_not_configured` | 503 | `use_context_with_your_model` | 这个部署没有配置回答模型：用 [`POST /v2/retrieval/context`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-buildcontext) 构建上下文包，交给你自己的模型。 |
| `deadline_exceeded` | 504 | `retry_later` | 检索超过了请求里的 `deadline_ms`。 |

## 下一步

- [API 约定](https://mirabase.io/zh/developers/conventions.md#errors)：错误信封、重试和限流。
- [SDK](https://mirabase.io/zh/developers/sdks.md#errors)：SDK 抛出的错误类型。
- [API 参考](https://mirabase.io/zh/developers/api.md)：每个接口可能返回的状态码。
