错误码
Markdown 版API Key 可能收到的每个错误码,及其 HTTP 状态码、remediation.action、含义和 Retry-After。
这张表从 OpenAPI 规格生成。错误信封的结构、重试策略和限流规则见 API 约定。按 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= 或 PUT /v2/spaces/ext:<external_id> 获取;如果看不到,请换一个 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 构建上下文包,交给你自己的模型。 |
deadline_exceeded | 504 | retry_later | 检索超过了请求里的 deadline_ms。 |
